uiautodev inspects Android and iOS UI hierarchies in the browser and writes the XPath for you

An inspector that lives in a browser tab

uiautodev is described as a mobile UI viewer in a browser, with a tree view of the UI and automatic XPath generation. The README's own one-liner is broader: a UI Inspector for Android, iOS and Harmony that helps inspect element properties and auto-generate XPath and script.

The browser is the point. Mobile developers are used to platform-specific inspectors, a separate app on the device that you activate with a gesture, that shows a hierarchy on the phone screen. Putting the tree in a desktop browser changes the ergonomics: you can search it, copy from it, keep it open next to your code, and use the browser's own developer tools to inspect the inspector.

The hosted service is at web.uiauto.dev, and the README also points to a separate domain for use in China. The examples directory contains a harmony-video.html file, and the repository carries a chrome_plugin/ directory, so the project has both a browser extension and a standalone web front end.

The topics in the repository metadata are automation, inspector, mobile-app and treeview. Automation is there because the tool records scripts and produces selectors, not because it runs a test suite, and that distinction is the one to keep in mind when deciding whether this is the right dependency.

The package metadata describes it as Mobile UI Automation, include UI hierarchy inspector, script recorder, with the homepage set to the web service. The author is codeskyblue, and the licence is MIT.

So the practical workflow is: connect a device, open the inspector, click a node in the tree, read its properties, copy the XPath, paste it into your script.

A Python CLI that downloads a separate server binary

The architecture is unusual enough to be worth describing precisely, because it explains most of the CLI's options.

The pip package is the Python side. It installs a command called uiauto.dev, and separately a command called uiautodev, both mapped to uiautodev.__main__:main in the package metadata. When you run uiauto.dev with no command, it downloads a prebuilt server binary for the current platform and executes it as run -open.

The binary is cached at ~/.cache/uiautodev/<version>/, and the cache location can be overridden with the UIAUTODEV_CACHE_DIR environment variable. The download command prints the path, the path command prints it without downloading anything, and the force flag re-downloads even if the file is cached.

Everything after run is passed through to the binary as-is. That is why uiauto.dev run -addr :8000 works as a port override, and why uiauto.dev --version 0.10.5 run pins a specific server build while the Python package itself stays on whatever version pip installed.

The global options are -v for verbose mode, --debug for debug output, --version for the server binary version with a default of latest, and -f for forcing a re-download.

Two commands are marked deprecated: server, which starts the local Python server, and shutdown. The README notes that the old local-server default is now the explicit uiauto.dev server command, so if you have muscle memory or a script calling uiauto.dev server, it still works but you should know it is on the way out.

Installing, and the difference between the pip package and the server

Installation is one command, and the HarmonyOS variant is an extra:

pip install uiautodev

pip install "uiautodev[harmony]"

The extra exists because the HarmonyOS driver needs a different library. In the dependency list the hypium package is marked optional with a version range of >=6.0.7.200 and <7.0.0, and the extras table maps harmony to hypium. The README links the Huawei developer documentation for the Hypium Python guidelines alongside that install line.

That is a small but useful design decision. Supporting a third platform does not force every user to install its driver, and the extra keeps the base install light.

The rest of the runtime dependency list explains what the tool is doing underneath. uiautomator2 at >=3.2.0 and <4 is the default Android driver, adbutils at >=2.8.10 and <3 is the adb layer, and wdapy at >0.2.2 and <1 sits alongside them. fastapi with uvicorn and websockets cover the server and its streaming, pydantic handles the data model, httpx is the HTTP client, and Pillow, lxml and construct are there for the image and XML handling that a UI hierarchy dump implies. pygments and rich cover the coloured output in the terminal.

Python 3.8 is the floor in the dependency declaration, and the project is built with poetry-core plus poetry-dynamic-versioning, with the version derived from the git tag rather than written by hand.

So a first run is: pip install the package, connect a device with adb, and run uiauto.dev, which fetches the server binary and opens the browser.

Which driver you are on changes how the tree is built

The environment section is two lines of prose and one line of shell, and it is the most consequential configuration in the project:

export UIAUTODEV_USE_ADB_DRIVER=1

The default driver is uiautomator2, and setting that environment variable switches to the adb driver. The README does not explain the trade-off, which is itself informative: the default is the higher level one, and the adb driver is the lower level path that talks to the device directly.

That difference is not cosmetic. uiautomator2 gives you a normalised element tree with stable accessors and a service on the device; raw adb gives you what the accessibility and view hierarchies actually contain, including the nodes you would not normally think of as addressable. Someone debugging why an automation cannot find an element is often exactly the person who wants the raw tree rather than the normalised one.

The switch is by environment variable rather than a command flag, which is a real constraint for automation. It means the driver is fixed for the process, so a shell script that wants to compare the two views has to set the variable before launching rather than passing an argument, and a CI job that differs from a developer's laptop in this respect will produce a different tree without an obvious cause.

The repository layout backs up the tool being more than a wrapper. There is a uiautodev/ package directory, an examples/ directory, a chrome_plugin/ directory for the browser extension, an e2etests/ directory and a tests/ directory, a pytest.ini and a .coveragerc, and a codecov.yml, so the project has both unit and end to end testing with coverage tracking.

Offline mode, and the local server that predates the binary

The offline mode is the answer to a problem the hosted service creates. If the inspector lives in a browser tab pointing at web.uiauto.dev, then working on a device with no network access, or in an environment where you cannot send traffic to a third party, breaks the workflow.

Starting the server in offline mode:

uiautodev server --offline

And with an explicit server URL, which is optional:

uiautodev server --offline --server-url https://web.uiauto.dev

The behaviour is described as: visit http://localhost:20242 once, and then disconnecting from the internet will not affect usage. All frontend resources will be saved to the cache/ directory. So the page is fetched once, the assets are kept locally, and the tool keeps working with the network pulled out.

That is a sensible fallback and it explains why the local server command still exists at all, even though it is marked deprecated. The binary-based default is faster and simpler for the common case, but the local Python server with the offline flag is the one that does not need the internet.

The port 20242 appears in the offline instructions and in the Makefile's dev and mock targets, which start the server with --reload on that port, and the mock target adds a --mock flag. So the developer workflow is a reloadable local server on a fixed port, and the mock mode is there to drive the UI without a device attached.

The Makefile also shows the project's own tooling: format runs isort with a hanging indent and a 120 character line length, test runs pytest against the tests directory, cov adds coverage reporting in both XML and terminal form, and build removes dist/ before running poetry build.

Where uiautodev stops and a test framework starts

The first limit is that this is an inspection tool with a recorder attached, not an execution engine. The description says script recorder, and the generated output is XPath and recorded actions. Nothing here runs your script against a device, schedules it, retries it or reports on it. If you need a test suite that runs on every commit, you need a runner, and uiautodev is the tool you would use to find the selectors that runner needs.

The second limit is platform reach. The three platforms named are Android, iOS and HarmonyOS. The dependency list is dominated by Android tooling, with uiautomator2 and adbutils as the core, and wdapy sitting alongside them. The iOS support is present in the description but no iOS-specific driver appears in the dependency list, which suggests it arrives with the server binary rather than through Python. Anyone whose target is iOS should check what the binary actually needs before committing.

The third limit is the download model. The tool fetches a prebuilt server binary from the network on first use and executes it. That is convenient, and it means the Python package version and the server binary version can drift, which is why there is a --version option to pin the server separately. It also means the tool cannot run on a locked down machine with no outbound access unless you use the offline local server path, and it means you are executing a binary whose provenance you have to take on trust.

The alternative to weigh is the platform's own tooling. adb has uiautomator dump for a raw hierarchy, and Xcode has its accessibility inspector for iOS, all of which are already installed with the platform and require no separate service to be downloaded. The difference in approach is scope and convenience. The native tools give you the tree on the device and little else, and on iOS they require a Mac and a device connection. uiautodev gives you the same information in a desktop browser with search, generated XPath and a script recording, plus a hosted version you can point a colleague at without installing anything. For exploring an unfamiliar app quickly, the browser tree is the faster path; for a fixed test suite that runs in CI, the native tools and your own runner are the better foundation.

Editorial conclusion

Adopt uiautodev if you need to inspect what an app actually renders and get a selector for each element, since the tree view and generated XPath are the whole product and the browser UI avoids a native inspector you would have to install per device. Do not adopt it as a full automation framework, because it inspects and records rather than driving a test suite, and check that the default uiautomator2 driver matches your device setup. Verify first which driver you are on, since the adb driver is switched by an environment variable rather than a flag, that the server binary can be downloaded for your platform, and whether the HarmonyOS extra applies to you.

Frequently asked questions

Official sources

1. codeskyblue/uiautodev on GitHub
2. License: MIT
3. Project website
4. README
5. Releases