LocatorLens

Real-time Element Inspector & Locator Generator for Appium (Android & iOS)

Inspect mobile app elements, generate locators, and see a live screen mirror — all from your browser. Works with any app on any device, no code changes or app modifications required.

Features

Inspector

Works with any app — inspect any foreground app without reconfiguration
Live Screen Mirror — see your device screen in real time at up to 30 FPS
Click to Inspect — click anywhere on the mirrored screen to select that element
Hover to Highlight — hover over elements in the tree to highlight them on screen
Visual Element Tree — full XML hierarchy browser with expand/collapse
Search Elements — filter the element tree by attribute name or value
Auto-refresh — detects screen changes and refreshes page source automatically

Locator Generation

All strategies at once — XPath, Resource ID, Content Description, UIAutomator2, Accessibility ID, iOS Class Chain, NSPredicate String
Ranked by reliability — best locators shown first (ID > Accessibility > XPath)
Uniqueness badge — green checkmark if unique, orange warning if multiple elements match
One-click copy — copy any locator directly to your clipboard

Developer Experience

Appium Methods Preview — see what getText(), getAttribute(), getRect(), isEnabled() etc. would return for the selected element, before writing a single line of test code
Interact Mode — tap elements directly from the browser to navigate the app
Dark / Light theme — persists across sessions
Auto-reconnect — WebSocket reconnects automatically if the backend restarts
Built-in log viewer — filterable, full-page log view with Info / Warning / Error levels

Overview

Extension Home

Start and monitor the LocatorLens servers directly from the Chrome extension popup.

Inspector

Inspect any foreground app, view the live screen mirror, browse the element tree, and copy generated locators in one place.

Quick Start

Get up and running in under 5 minutes.

Install prerequisites — Node.js 18+, Appium 2.x, and the relevant driver (see Prerequisites)
Install the extension — add from Chrome Web Store or load unpacked (see Installation)
Run the auto setup installer — from the extension's Settings page
Connect your device — start your Android device (USB debugging on) or boot an iOS simulator
Click the extension icon → Start Servers → select platform and device → Connect
Start inspecting — click any element on the screen mirror to see all its locators

That's it. Open any app on your device and keep inspecting — no reconnection needed.

Prerequisites

Requirement	Version	Purpose	Install
Node.js	18+	Runs the backend server	nodejs.org
Appium	2.x	Mobile automation server	`npm install -g appium`
UIAutomator2 driver	latest	Android support	`appium driver install uiautomator2`
XCUITest driver	latest	iOS support (macOS only)	`appium driver install xcuitest`
ADB	latest	Android device communication	Android Platform Tools
Xcode	latest	iOS simulator support (macOS only)	Mac App Store

Installation

Option 1 — Chrome Web Store (Recommended)

Install LocatorLens from the Chrome Web Store
Click the extension icon → Settings
Follow the Setup Guide on the settings page — it downloads the auto setup installer and registers the local companion

Option 2 — Load Unpacked (Developers)

# Clone the repo
git clone https://github.com/pritesh1991/LocatorLens.git
cd LocatorLens

# Install backend dependencies
cd backend && npm install && cd ..

Then load the extension in Chrome:

Go to chrome://extensions
Enable Developer Mode (top right)
Click Load Unpacked → select the /extension folder

Then install the local companion from the extension itself:

Open the loaded LocatorLens extension's Settings page
Download the auto setup installer for your platform
Run the downloaded installer, then reload the extension

The Settings-page installer bakes in your actual unpacked extension ID. If you run the repository installer directly, pass your extension ID explicitly:

# macOS / Linux
bash extension/installers/install_host.sh --extension-id <your-extension-id>

# Windows (Command Prompt)
extension\installers\install_host.bat --extension-id <your-extension-id>

How It Works

[Chrome Extension]
       |  native messaging
       v
[Native Host (Node.js)]  ──starts──►  [Backend Server :8765]
                                               │
                              WebSocket / REST │
                                               ▼
                                      [Appium Server :4723]
                                               │
                                               ▼
                                    [Android / iOS Device]
                                    (any app, any screen)

Extension sends a start command to a native host via Chrome's native messaging API
Native host starts the Node.js backend and Appium server
Extension connects to the backend over WebSocket for live screen streaming
Backend uses Appium to capture screenshots and page source XML for whatever app is in the foreground
Extension renders the screen mirror and generates locators from the XML

Settings

Open the extension Settings page to configure:

Setting	Default	Description
Backend Port	`8765`	Port the Node.js backend listens on
Appium URL	`http://localhost:4723`	Appium server address and port
Screen Mirror FPS	`3`	Frames per second for live screen streaming (1–30)
Theme	`Dark`	Light or dark appearance for Settings and Inspector

Backend Port and Appium URL take effect on the next Start Servers. Screen Mirror FPS is applied when streaming starts, and an open inspector updates its active stream after you save a new FPS value. Theme changes apply immediately.

Platform Support

Platform	Android	iOS Simulator	Notes
macOS	✅	✅	Full support
Windows	✅	❌	iOS requires macOS
Linux	✅	❌	iOS requires macOS

LocatorLens and Appium Inspector Workflows

LocatorLens is built for Appium-based workflows and is inspired by the fast visual feedback people expect from inspector tools like Appium Inspector.

Feature	LocatorLens	Appium Inspector / Desktop Inspector Workflow
Distribution	Chrome Extension — no install, auto-updates	Desktop app — manual download & updates
Startup	One click	Manual: start Appium, configure capabilities, create session
Session setup	Zero config — inspects whatever is on screen	Requires capabilities JSON per app
Live screen mirror	✅ Continuous up to 30 FPS	❌ Static snapshot
Auto-refresh on change	✅ Detects screen changes automatically	❌ Manual refresh
Multi-strategy output	✅ All 7+ strategies simultaneously	One at a time
Uniqueness validation	✅ Match count badge	❌ Not available
Click to inspect	✅ On live mirror	Static screenshot
Interact mode	✅ Tap from browser	Separate panel
App switching	✅ Any app, no reconfiguration	New session required
Log viewer	✅ Built-in with filtering	Separate terminal
Dark / light theme	✅	Varies by tool

When to use Appium Inspector or desktop inspector tools: Deep session configuration, remote automation grids, advanced capability tweaking.

When to use LocatorLens: Day-to-day locator building, exploratory testing, fast iteration.

Troubleshooting

Issue	Solution
"Native messaging host not found"	Re-run the installer from Settings and reload the extension
"Access forbidden" error	Re-run the installer (extension ID changed), then reload
Servers won't start	Check the log viewer in the popup. Ensure Node.js ≥ 18 is installed
Appium not found	`npm install -g appium` (use Command Prompt on Windows, not PowerShell)
UiAutomator2 driver missing	`appium driver install uiautomator2`
No Android devices listed	Enable USB debugging. Run `adb devices` in terminal
No iOS simulators listed	Boot a simulator in Xcode first (macOS only)
Screen capture fails	Check logs. Try disconnecting and reconnecting
Backend dependencies missing	Re-run the installer — it runs `npm install` automatically

Log file location:

macOS / Linux: ~/.locatorlens/native-host.log
Windows: %USERPROFILE%\.locatorlens\native-host.log

Project Structure

locatorlens/
├── backend/                    # Node.js REST + WebSocket server
│   ├── server.js
│   ├── appium-client.js
│   ├── device-manager.js
│   ├── screen-mirror.js
│   └── config.js
├── extension/                  # Chrome Extension (Manifest V3)
│   ├── manifest.json
│   ├── background.js
│   ├── popup/
│   ├── inspector/
│   ├── options.html / options.js
│   ├── logs.html / logs.js
│   └── installers/             # auto setup installers + companion metadata
├── native-host/                # Native messaging host
│   └── launcher.js
└── README.md

Attribution

LocatorLens was created by Pritesh Patel.

If you publish videos, articles, demos, forks, modified versions, redistributed packages, or other public material based on LocatorLens, please clearly credit:

LocatorLens by Pritesh Patel
https://github.com/pritesh1991/LocatorLens

Do not present LocatorLens or modified versions of LocatorLens as your original work without attribution. See NOTICE.md.

Name		Name	Last commit message	Last commit date
backend		backend
docs		docs
extension		extension
native-host		native-host
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
NOTICE.md		NOTICE.md
PRIVACY_POLICY.md		PRIVACY_POLICY.md
README.md		README.md
install_host.bat		install_host.bat
install_host.sh		install_host.sh
package.json		package.json

Navigation Menu

Repository files navigation

LocatorLens

Table of Contents

Features

Overview

Extension Home

Inspector

Quick Start

Prerequisites

Installation

Option 1 — Chrome Web Store (Recommended)

Option 2 — Load Unpacked (Developers)

How It Works

Settings

Platform Support

LocatorLens and Appium Inspector Workflows

Troubleshooting

Project Structure

Attribution

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

LocatorLens

Table of Contents

Features

Overview

Extension Home

Inspector

Quick Start

Prerequisites

Installation

Option 1 — Chrome Web Store (Recommended)

Option 2 — Load Unpacked (Developers)

How It Works

Settings

Platform Support

LocatorLens and Appium Inspector Workflows

Troubleshooting

Project Structure

Attribution

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages