hub / github.com/appium/appium-uiautomator2-driver
github.com/appium/appium-uiautomator2-driver @v8.1.0
Chat with this repo
235 symbols
679 edges
82 files
8 documented · 3%
6 cross-repo links
● updated 1d agov8.1.0 · 2026-07-04★ 85221 open issues
What it actually does AI analysis from the code graph — generated when you open this
loading…
README
Appium UiAutomator2 Driver
Appium UiAutomator2 Driver is a test automation framework for Android devices. Appium UiAutomator2 Driver automates native, hybrid and mobile web apps, tested on emulators and real devices. Appium UiAutomator2 Driver is part of the Appium mobile test automation tool. The driver operates in scope of W3C WebDriver protocol with several custom extensions to cover operating-system specific scenarios.
UiAutomator2 Driver proxies most of the commands to UiAutomator2 server, which uses Google's UiAutomator framework under the hood. Some commands are proxied directly to appium-adb and other helpers built on top of Android platform tools.
See the end-to-end architecture diagram.
[!IMPORTANT] Since major version 5.0.0, this driver is only compatible with Appium 3. Use the
appium driver install uiautomator2command to add it to your distribution.
Requirements
On top of standard Appium requirements UiAutomator2 driver also expects the following prerequisites:
- Windows, Linux and macOS are supported as hosts
- Android SDK Platform tools must be installed. Android Studio IDE also provides a convenient UI to install and manage the tools.
- ANDROID_HOME or ANDROID_SDK_ROOT environment variable must be set
- Java JDK must be installed and JAVA_HOME environment variable must be set. Android SDK below API 30 requires Java 8. Android SDK 30 and above requires Java 9 or newer.
- Emulator platform image must be installed if you plan to run your tests on it. Android Studio IDE also provides a convenient UI to install and manage emulators.
- Real Android devices must have USB debugging enabled and should be visible as
onlineinadb devices -loutput. - Since driver version 6.0.0 the minimum supported version of Android API is 8/Oreo (API level 26). Before version 6.0.0 the minimum supported version of Android API is 5 (API level 21). 6.0 is recommended as version 5 has some known compatibility issues.
Doctor
Since driver version 2.39.0 you can automate the validation for the most of the above
requirements as well as various optional ones needed by driver extensions by running the
appium driver doctor uiautomator2 server command.
Capabilities
General
| Capability Name | Description |
|---|---|
| platformName | Could be set to android. Appium itself is not strict about this capability value if automationName is provided, so feel free to assign it to any supported platform name if this is needed, for example, to make Selenium Grid working. |
| appium:automationName | Must always be set to uiautomator2. Values of automationName are compared case-insensitively. |
| appium:deviceName | The name of the device under test (actually, it is not used to select a device under test). Consider setting udid for real devices and avd for emulators instead |
| appium:platformVersion | The platform version of an emulator or a real device. This capability is used for device autodetection if udid is not provided |
| appium:udid | UDID of the device to be tested. Could be retrieved from adb devices -l output. If unset then the driver will try to use the first connected device. Always set this capability if you run parallel tests. |
| appium:noReset | Prevents the device to be reset before the session startup if set to true. This means that the application under test is not going to be terminated neither its data cleaned. false by default |
| appium:fullReset | Being set to true always enforces the application under test to be fully uninstalled before starting a new session. false by default |
| appium:printPageSourceOnFindFailure | Enforces the server to dump the actual XML page source into the log if any error happens. false by default. |
Driver/Server
| Capability Name | Description |
|---|---|
| appium:systemPort | The number of the port on the host machine used for the UiAutomator2 server. By default the first free port from 8200..8299 range is selected. It is recommended to set this value if you are running parallel tests on the same machine. |
| appium:skipServerInstallation | Skip the UiAutomator2 Server component installation on the device under test and all the related checks if set to true. This could help to speed up the session startup if you know for sure the correct server version is installed on the device. In case the server is not installed or an incorrect version of it is installed then you may get an unexpected error later. false by default |
| appium:uiautomator2ServerLaunchTimeout | The maximum number of milliseconds to wait util UiAutomator2Server is listening on the device. 30000 ms by default |
| appium:uiautomator2ServerInstallTimeout | The maximum number of milliseconds to wait util UiAutomator2Server is installed on the device. 20000 ms by default |
| appium:uiautomator2ServerReadTimeout | The maximum number of milliseconds to wait for a HTTP response from UiAutomator2Server. Only values greater than zero are accepted. If the given value is too low then expect driver commands to fail with timeout of Xms exceeded error. 240000 ms by default |
| appium:disableWindowAnimation | Whether to disable window animations when starting the instrumentation process. The animation scale will be restored automatically after the instrumentation process ends for API level 26 and higher. The animation scale could remain if the session ends unexpectedly for API level 25 and lower. false by default |
| appium:skipDeviceInitialization | If set to true then device startup checks (whether it is ready and whether Settings app is installed) will be canceled on session creation. Could speed up the session creation if you know what you are doing. false by default |
App
| Capability Name | Description |
|---|---|
| appium:app | Full path to the application to be tested (the app must be located on the same machine where the server is running). Both .apk and .apks application extensions are supported. Could also be an URL to a remote location. If neither of the app, appPackage or browserName capabilities are provided then the driver starts from the Dashboard and expects the test knows what to do next. Do not provide both app and browserName capabilities at once. |
| browserName | The name of the browser to run the test on. If this capability is provided then the driver will try to start the test in Web context mode (Native mode is applied by default). Read Automating hybrid apps for more details. Usually equals to chrome. |
| appium:appPackage | Application package identifier to be started. If not provided then UiAutomator2 will try to detect it automatically from the package provided by the app capability. Read How To Troubleshoot Activities Startup for more details |
| appium:appActivity | Main application activity identifier. If not provided then UiAutomator2 will try to detect it automatically from the package provided by the app capability. Read How To Troubleshoot Activities Startup for more details |
| appium:appWaitActivity | Identifier of the first activity that the application invokes. If not provided then equals to appium:appActivity. Read How To Troubleshoot Activities Startup for more details |
| appium:appWaitPackage | Identifier of the first package that is invoked first. If not provided then equals to appium:appPackage. Read How To Troubleshoot Activities Startup for more details |
| appium:appWaitDuration | Maximum amount of milliseconds to wait until the application under test is started (e. g. an activity returns the control to the caller). 20000 ms by default. Read How To Troubleshoot Activities Startup for more details |
| appium:androidInstallTimeout | Maximum amount of milliseconds to wait until the application under test is installed. 90000 ms by default |
| appium:appWaitForLaunch | Whether to block until the app under test returns the control to the caller after its activity has been started by Activity Manager (true, the default value) or to continue the test without waiting for that (false). |
| appium:intentCategory | Set an optional intent category to be applied when starting the given appActivity by Activity Manager. Defaults to android.intent.category.LAUNCHER. Please use mobile:startActivity in case you don't set an explicit value. |
| appium:intentAction | Set an optional intent action to be applied when starting the given appActivity by Activity Manager. Dfaults to android.intent.action.MAIN. Please use mobile:startActivity in case you don't set an explicit value. |
| appium:intentFlags | Set an optional intent flags to be applied when starting the given appActivity by Activity Manager. Defaults to 0x10200000 (FLAG_ACTIVITY_NEW_TASK |
| appium:optionalIntentArguments | Set an optional intent arguments to be applied when starting the given appActivity by Activity Manager |
| appium:dontStopAppOnReset | Set it to true if you don't want the application to be restarted if it was already running. If appium:noReset is falsy, then the app under test is going to be restarted if either this capability is falsy (the default behavior) or appium:forceAppLaunch is set to true. false by default |
| appium:forceAppLaunch | Set it to true if you want the application under test to be always forcefully restarted on session startup even if appium:noReset is true, and the app was already running. If noReset is falsy, then the app under test is going to be restarted if either this capability set to true or appium:dontStopAppOnReset is falsy (the default behavior). false by default. Available since driver version 2.12 |
| appium:shouldTerminateApp | Set it to true if you want the application under test to be always terminated on session end even if appium:noReset is true. If noReset is falsy, then the app under test is going to be terminated if appium:dontStopAppOnReset is also falsy (the default behavior). false by default |
| appium:autoLaunch | Whether to launch the application under test automatically (true, the default value) after a test starts |
| appium:autoGrantPermissions | Whether to grant all the requested application permissions automatically when a test starts(true). The targetSdkVersion in the application manifest must be greater or equal to 23 and the Android version on the device under test must be greater or equal to Android 6 (API level 23) to grant permissions. Applications whose targetSdkVersion is lower than or equal to 22 must be reinstalled to grant permissions, for example, by setting the appium:fullReset capability as true for Android 6+ devices. If your app needs some special security permissions, like access to notifications or media recording, consider using mobile: changePermissions extension with appops target. false by default |
| appium:otherApps | Allows to set one or more comma-separated paths to Android packages that are going to be installed along with the main application under test. This may be useful if the tested app has dependencies |
| appium:uninstallOtherPackages | Allows to set one or more comma-separated package identifiers to be uninstalled from the device before a test starts |
| appium:allowTestPackages | If set to true then it would be possible to use packages built with the test flag for the automated testing (literally adds -t flag to the adb install command). false by default |
| appium:remoteAppsCacheLimit | Sets the maximum amount of application packages to be cached on the device under test. This is needed for devices that don't support streamed installs (Android 7 and below), because ADB must push app packages to the device first in order to install them, which takes some time. Setting this capability to zero disables apps caching. 10 by default. |
| appium:enforceAppInstall | If set to true then the application under test is always reinstalled even if a newer version of it already exists on the device under test. This capability has no effect if appium:noReset is set to true. false by default. |
App Localization
| Capability Name | Description |
|---|---|
| appium:localeScript | Canonical name of the locale to be set for the app under test, for example Hans in zh-Hans-CN. See https://developer.android.com/reference/java/util/Locale.html for more details. |
| appium:language | Name of the language to extract application strings |
Extension points exported contracts — how you extend this code
Uiautomator2SessionInfo (Interface)(no doc)
lib/types.ts
BatteryInfo (Interface)
(no doc)
lib/commands/types.ts
UiAutomatorEmitterContext (Interface)
(no doc)
lib/css/ui-automator-emitter.ts
PackageInfo (Interface)
(no doc)
lib/uiautomator2-server/core.ts
Uiautomator2DeviceDetails (Interface)
(no doc)
lib/types.ts
InstallOptions (Interface)
(no doc)
lib/commands/types.ts
UiAutomator2ServerOptions (Interface)
(no doc)
lib/uiautomator2-server/core.ts
Uiautomator2ServerInfo (Interface)
(no doc)
lib/types.ts
Core symbols most depended-on inside this repo
initSessioncalled by 34
test/functional/helpers/session.ts
deleteSession
called by 29
test/functional/helpers/session.ts
isEmpty
called by 23
lib/utils/lang.ts
amendCapabilities
called by 21
test/functional/desired.ts
parseSurfaceFlingerDisplays
called by 14
lib/commands/screenshot.ts
registerActiveSession
called by 13
lib/session-claim-handler.ts
makeDriver
called by 11
test/unit/session-claim-handler-specs.ts
isCi
called by 11
test/functional/helpers/ci-e2e.ts
Shape
Languages
TypeScript100%
Modules by API surface
lib/uiautomator2-server/core.ts23 symbols
lib/driver.ts18 symbols
lib/commands/element.ts17 symbols
lib/session-claim-handler.ts16 symbols
lib/commands/gestures.ts14 symbols
test/functional/commands/keyboard/keyboard-e2e-specs.ts12 symbols
lib/css/ui-automator-emitter.ts12 symbols
test/unit/session-claim-handler-specs.ts11 symbols
lib/uiautomator2-server/session.ts11 symbols
lib/commands/types.ts8 symbols
lib/commands/viewport.ts7 symbols
lib/commands/misc.ts7 symbols
Used by 6 indexed graphs manifest dependencies, hub-wide
For agents
$ claude mcp add appium-uiautomator2-driver \
-- python -m otcore.mcp_server <graph>