Android UI Inspector

What is an Android UI Inspector?

An Android UI inspector helps developers and testers understand the controls that make up an application's current screen. A person sees buttons, text fields, cards, menus, and images. An automation framework instead needs machine-readable properties such as a resource ID, accessibility description, class name, visible text, element bounds, or a path through the view hierarchy. This tool displays those two views together: the captured phone screen on one side and the corresponding UIAutomator node hierarchy on the other.

After you select an element, the inspector shows its package, Android class, resource ID, text, content description, screen bounds, clickable state, and scrollable state. It also generates four practical outputs: an Appium locator, a Python UIAutomator2 expression, an XPath, and an ADB tap command using the centre of the element's bounds. The purpose is not merely to display XML. It is to shorten the path from seeing a control on a phone to using a maintainable locator in a real test or automation script.

How the browser-based Android inspection works

The connection starts only after you press Connect phone. Chrome or Edge opens its own device chooser, and no device can be selected silently by the page. Once you choose the Android phone, the browser creates an ADB connection through WebUSB. Android then displays the normal USB debugging authorization prompt. You must approve that prompt on the physical phone before the browser can run inspection commands.

When you press Inspect screen, the tool requests a PNG screenshot and asks Android UIAutomator to dump the active accessibility hierarchy. It parses that hierarchy in the browser, matches each node's bounds to the screenshot, and builds the searchable tree. Moving over the screenshot highlights the smallest element containing the pointer. Clicking locks the selection so you can inspect its attributes and copy a locator.

This is a snapshot rather than continuous screen mirroring. If the app changes, navigate on the phone and press Inspect screen again. Snapshot-based inspection keeps the workflow focused and avoids running a permanent video stream or remote-control service.

Requirements before connecting your Android phone

• Use a desktop version of Google Chrome or Microsoft Edge with WebUSB enabled.
• Open DevCalc over HTTPS. WebUSB is restricted to secure browser contexts.
• Enable Developer options and USB debugging on the Android phone.
• Use a USB cable that carries data; charge-only cables cannot expose the debugging interface.
• Unlock the phone and keep its screen awake while approving the debugging prompt.
• Close Android Studio, desktop ADB, Appium, scrcpy, or another program if it has exclusively claimed the USB interface.

On some Windows computers, the phone manufacturer's USB or ADB driver must be installed before the browser can see the debugging interface. If the browser chooser is empty, first confirm that the cable and USB debugging work on that computer, then reconnect the device and try again.

How to use the Android UI Inspector

1. Prepare the screen you want to inspect

Open the target application on the phone and navigate to the exact state used by your test. Expand the menu, open the dialog, or focus the input if that state affects which controls Android exposes. An inspector can describe only the hierarchy that exists at capture time.

2. Connect and authorize the device

Choose Connect phone, select the device in the browser window, and approve the RSA debugging prompt on Android. Read the computer identity shown by Android before accepting it. On a shared or untrusted machine, avoid selecting the option that permanently remembers the computer.

3. Capture the current interface

Choose Inspect screen. The page displays the screenshot and hierarchy when both are available. If the application moves or animates while the two captures are being taken, inspect again after the screen becomes stable so the node bounds align with the image.

4. Select and verify an element

Point to the visible control or search the tree by text, ID, description, or class. The blue overlay shows the element under the pointer, while the yellow overlay marks the selected element. Check that the bounds and attributes belong to the intended control rather than a large parent container.

5. Copy the most stable locator

Copy the resource-ID or accessibility-based locator when one is available. Before placing it in a test suite, confirm that it identifies the intended element uniquely and remains the same after reopening the screen. Generated output is a strong starting point, but the application decides whether its IDs, labels, and hierarchy are stable.

Android selector priority and trade-offs

Resource ID

A resource ID such as com.example:id/sign_in is normally the first choice. It is explicit, fast for automation frameworks to locate, and independent of physical screen coordinates. IDs can still change during application refactoring, and repeated list layouts can contain multiple elements with the same ID, so uniqueness must be checked in context.

Accessibility ID or content description

Appium maps an Android content description to an accessibility-ID locator. This is often stable and encourages accessible application design. It is especially useful for icon-only controls that have no visible text. The description should be meaningful and unique rather than a visual instruction such as "blue button."

Visible text

Text locators are readable and convenient for prototypes, but they can change with copy edits, user data, localization, capitalisation, or whitespace. They are best used when the text is intentional, predictable, and scoped to the correct part of the interface.

XPath

XPath can express relationships that a single attribute cannot, including parent, child, class, and index conditions. A short attribute-based XPath may be reasonable. A long absolute path through many containers is fragile because inserting one wrapper can invalidate it. Prefer the smallest expression that distinguishes the control.

ADB tap coordinates

The generated ADB command taps the centre of the reported bounds. Coordinates are helpful for quick device diagnostics or controls that expose no usable node, but they are tied to resolution, orientation, display scaling, keyboard state, and layout. They should be treated as a fallback rather than the default locator strategy.

Two main uses: get selectors and build automation

1. Get the correct selector from the Android screen

Open the required app screen, inspect it, and click the exact button, input, menu, card, or list item you want to automate. The tool maps that visual position to the smallest matching UIAutomator node and shows its resource ID, text, accessibility description, class, package, bounds, clickability, and scrollability. You can then copy the Appium locator, UIAutomator2 expression, XPath, or ADB tap command instead of guessing it manually.

This is useful both when creating a new script and when repairing an existing script after an app update. If a locator stopped working, inspect the new screen and compare the current resource ID, text, description, and hierarchy with the old selector. Prefer the most stable unique attribute and use XPath or coordinates only when the application exposes no better option.

2. Build Android automation with the copied selector

Paste the copied selector into an Appium or Python UIAutomator2 script and attach the required action. A login flow might wait for a username field, type text, locate the password field, type the password, and click the sign-in button. A Gmail workflow might open the search field, enter a sender, wait for a matching message, open it, and locate a call-to-action button. The inspector supplies the element locator; your automation code defines the action, wait conditions, error handling, and sequence.

Selectors can support actions such as click, long-click, type, clear, wait until visible, verify text, check enabled state, swipe to an element, or confirm that a screen opened successfully. For maintainable automation, group selectors by screen or page object, add explicit waits instead of fixed sleeps, and verify each important transition before continuing to the next step.

Privacy and security

The ADB transport, screenshot bytes, hierarchy XML, element search, and selector generation run in the browser tab. DevCalc does not provide a server endpoint for this inspection data. The page cannot connect before you press the connection button, choose a device through the browser's protected prompt, and authorize debugging on Android.

ADB access is powerful. Inspect only devices you own or are authorized to test, and connect them only on a computer you trust. Screenshots and UI hierarchies can contain messages, account names, one-time codes, or other private information visible in the active application. Close the tab when finished. On an untrusted computer, revoke USB debugging authorizations from Android Developer options after disconnecting.

Troubleshooting connection and hierarchy problems

The phone does not appear in the browser chooser

Try a different data-capable cable or USB port, unlock the phone, turn USB debugging off and on, and reconnect it. Confirm that the browser is Chrome or Edge on a desktop computer. Close software that may own the ADB interface. Windows may also require the correct manufacturer or ADB USB driver.

The connection waits for authorization

Look at the physical phone for the USB debugging dialog. If no dialog appears, disconnect the cable, revoke existing USB debugging authorizations, reconnect, and start the browser connection again. Do not approve a key when you do not recognise or trust the computer.

Appium is controlling the phone

The inspector deliberately stops when it detects the Appium UIAutomator2 server. End the Appium session and then capture the hierarchy. Running a second hierarchy tool during active automation can interrupt instrumentation and produce transport errors that look like selector failures.

The screenshot appears but controls are absent

Some games, video surfaces, WebViews, custom canvases, secure windows, and heavily customised components do not expose their internal visual content as normal UIAutomator nodes. You may see one large container instead of each visible item. In those cases, work with application developers to add accessibility semantics or use a testing method designed for that rendering technology.

The highlight does not align with the screen

Animations, rotation, a newly opened keyboard, or a changing status bar can cause the screenshot and hierarchy snapshots to represent slightly different moments. Wait until the layout is still and inspect again. Also keep the phone orientation unchanged until you finish selecting the element.

Limitations of an online Android UI inspector

WebUSB support is browser- and platform-dependent, and the tool requires physical access to the connected device. It does not inspect an Android emulator running on a remote service, connect through DevCalc's server, execute a complete test suite, record gestures, or guarantee that a generated locator is unique. It also cannot expose information that Android omits from its accessibility hierarchy.

The tool is designed for inspection and locator discovery. Test reliability still depends on application state management, waits, permissions, animations, network responses, device configuration, and the assertions in your automation framework. Treat generated selectors as inputs to a well-structured test rather than as a replacement for test design.

Technical references

The hierarchy is based on Android UI Automator concepts documented by Android Developers. Direct USB access uses the browser capability described by the WebUSB specification, with the open-source Tango ADB transport used by this implementation.