DroidBot: UI-guided input generation for Android apps

A generator that reads the screen before it acts

DroidBot is a lightweight test input generator for Android. It can send random or scripted input events to an Android app, achieve higher test coverage more quickly, and generate a UI transition graph after testing. A sample UTG is linked from the README, and the image at the top of the document shows the graph layout.

The design difference from the tool it is usually compared against is stated as a list of four advantages. It does not require system modification or app instrumentation. Its events are based on a GUI model instead of being random. It is programmable, so you can customise the input for certain UI. And it can produce UI structures and method traces for analysis.

The second point is the core of it. A random event generator has no idea what screen it is on, so most of its events are no-ops that land on a button which was not there. DroidBot asks the device for the current view hierarchy and chooses an input that the visible widget can actually respond to, which is why it reaches more of the app in less time. The reference for the approach is the ICSE-C 2017 paper, DroidBot: a lightweight UI-guided test input generator for Android, by Li, Yuanchun and others.

The tool is MIT licensed, the primary language is Python, and the last push to the master branch was on 2026-08-29 with no GitHub releases. The News section points at more recent work integrating LLMs with DroidBot for intelligent task automation on smartphones, in a separate project called AutoDroid.

Installing it, and the four prerequisites

The install is a clone and a pip install, and the setup.py calls the package a lightweight UI-guided test input generator for Android, version 1.0.2b4, with a Development Status of Beta and an intended audience of Developers.

git clone https://github.com/honeynet/droidbot.git
cd droidbot/
pip install -e .

The README says that if the install succeeded you should be able to execute droidbot -h, and the setup.py registers the console script droidbot=droidbot.start:main, so the entry point is a module inside the droidbot package rather than a top level script.

The prerequisites are five items. Python, and both version 2 and version 3 are supported. Java. The Android SDK. Adding the platform_tools directory in the Android SDK to PATH. And optionally OpenCV-Python if you want to run DroidBot in cv mode.

That last one is worth flagging, because it explains a design decision later. DroidBot's normal way of knowing what is on screen is the accessibility service, and an app that does not expose its views through accessibility leaves the tool blind. OpenCV is the fallback that lets it look at the screen instead.

One dependency note is in a comment in the setup.py itself: androidviewclient does not support pip install, so you should install it with easy_install. The install_requires list is otherwise short, with androguard at 3.4.0a1 or newer, networkx and Pillow.

Running a session, and the flags that shape it

A run needs two things: the .apk file path of the app you want to analyse, and a device or an emulator connected to your host machine via adb. Then:

droidbot -a <path_to_apk> -o output_dir

The README says that is it, and that you will find much useful information in the output dir, including the UTG.

The flags cover the situations you actually hit. With multiple devices connected you may need -d <device_serial> to specify the target, and the easiest way to get a serial is calling adb devices. On some devices you may need to manually turn on the accessibility service for DroidBot, which it requires to get the current view hierarchy. If you want to test a large scale of apps, the -keep_env option avoids re-installing the test environment every time.

The scripting option is the programmable-input feature. You can use a json-format script to customise input for certain states, with samples in the script_samples/ directory, and pass it with -script <path_to_script.json>.

Two options extend the reach. The -cv option helps when your apps do not support getting views through accessibility, and the README names the common case, most games based on Cocos2d and Unity3d. The -humanoid option lets DroidBot communicate with Humanoid to generate human-like test inputs.

And droidbot -h shows the rest.

The script_samples/ directory at the top level of the repository is the documentation for the scripting format, and the state-based approach is the interesting design point: a script says what to do when the app is in a particular state, which is a different model from a fixed sequence of taps.

The project layout, and who built it

The repository is small, and the structure tells you how the tool is put together.

At the top level there is setup.py and setup.cfg for the packaging, start.py as an entry point, the droidbot/ package itself, a script_samples/ directory with the JSON script examples, a.gitignore and the README. The setup.py packages are droidbot and droidbot.adapter, and the package_data entry includes everything found under droidbot/resources/, which is where the runtime assets such as the UTG illustration live.

Two details in the packaging are worth noting. The version is 1.0.2b4, a beta suffix on a 1.0.2, and the download_url points at a tarball for that same version, so the published artefact is a prerelease of the tool. The console script is registered under the name droidbot, mapping to droidbot.start:main, which means the module that the user invokes is start, not a file called droidbot.

The people behind it are named in the acknowledgements, and the list explains a lot about the project's shape. AndroidViewClient, which the setup.py comment says has to be installed with easy_install because it does not support pip. Androguard, which the install_requires list pins at 3.4.0a1 or newer. The Honeynet project, the security research organisation the repository is hosted under. And Google Summer of Code, which is where a project of this size usually starts.

The author is Yuanchun Li, and the droidbotApp source code lives in a separate repository under the ylimit organisation, alongside a page for how to contact the author. The blog posts on the project site are linked under Useful links.

The UTG as an artefact worth keeping

The UI transition graph is the output that makes DroidBot more than a fuzzing tool, and the README treats it as a first class result rather than a debug leftover.

A UTG records the states the app was in and the transitions between them, which means a test run produces a map of the application's navigable surface. That map is useful for more than coverage measurement. It shows which screens are reachable, which are not, and where the paths branch, and a graph of that shape is the kind of artefact that survives a release and can be diffed against the previous one.

The fourth listed advantage, that it can produce UI structures and method traces for analysis, is the companion capability. The method traces are what let you line up a transition with the code path that produced it.

The evaluation section explains how the tool was assessed, by running experiments testing apps with DroidBot and with Monkey, and the results are published as DroidBot posts on the project site. A sample evaluation report from 2015 is linked as well.

So the comparison is explicit and public. DroidBot is not claiming to replace Monkey, it is claiming that a model-driven generator gets further into an app in the same time, and the report is where you would check whether that holds for your kind of app. The known limitation is the one already noted, that an app which hides its views from accessibility gives the generator nothing to work with, which is why the cv mode and the Humanoid integration exist.

Editorial conclusion

Adopt DroidBot when you want a short automated test run that reaches deeper into an app than random events would, because it reads the current view hierarchy and picks inputs that make sense, and it hands you a UI transition graph afterwards for analysis. Do not adopt it as a replacement for a test suite, since it generates inputs rather than asserting behaviour. Before you run it, expect to enable the accessibility service on the device, and note the -cv mode for apps that do not expose their views through accessibility, which covers most games built on Cocos2d and Unity3d.

Frequently asked questions

Official sources

1. honeynet/droidbot on GitHub
2. Issues
3. License: MIT
4. README