Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 37 ยท Capabilities and Sessions

UiAutomator2 Capabilities for Android

Configure Android sessions with the UiAutomator2 driver: app vs appPackage and appActivity, permissions, resets, timeouts, and the capabilities that speed up tests.

The UiAutomator2 driver is Appium's workhorse for Android. It has dozens of capabilities, but a handful cover nearly every real test. This lesson groups them by purpose so you can pick the right ones: what to launch, how to start clean, how to handle permissions, and how to avoid slow or flaky startup.

Capability names are shown with their appium: prefix. Check the driver's own documentation for your installed version, because the list grows over time; the ones below have been long-standing.

What to launch

There are two ways to tell the driver which app to test.

Install and launch from a file. Set appium:app to the APK path (or a URL the server can download). The driver installs it (reinstalling if the version differs) and launches the main activity, which it reads from the APK manifest:

JSON
{ "platformName": "Android", "appium:automationName": "UiAutomator2", "appium:app": "/builds/shop-debug.apk" }

Use an installed app. Set appium:appPackage and appium:appActivity and omit app:

JSON
{
  "platformName": "Android",
  "appium:automationName": "UiAutomator2",
  "appium:appPackage": "com.example.shop",
  "appium:appActivity": ".ui.MainActivity"
}

Activity names beginning with a dot are relative to the package. Use appium:appWaitActivity (which may be a comma-separated list) when your launcher activity forwards to another activity, such as a splash screen, so the driver waits for the real one.

To discover the package and activity of an installed app, use adb shell dumpsys window | grep mCurrentFocus while the app is on screen, or aapt dump badging app.apk on the APK.

Which device

  • appium:udid: the adb serial. Required when more than one device is connected.
  • appium:avd: the name of an AVD. The driver starts the emulator for you and waits for boot, which is handy locally (appium:avdLaunchTimeout controls the wait).
  • appium:platformVersion and appium:deviceName: optional hints. Do not rely on deviceName to choose a device.

Starting clean or fast

Capability Effect
appium:noReset Do not clear app data between sessions. Faster, but tests may depend on earlier state.
appium:fullReset Uninstall the app and clear data first. Slowest, cleanest.
default (both false) Clears data before the session but keeps the app installed.
appium:dontStopAppOnReset Keep the app process running on reset
appium:forceAppLaunch Launch the app even when it is already running
appium:autoLaunch Set to false to start the session without launching any app

A common pattern is: fullReset on CI for the first test of a run, and default reset for the rest.

Permissions and dialogs

  • appium:autoGrantPermissions: grant all runtime permissions declared in the manifest at install time, so permission popups never appear. Use it by default, then test the permission dialog flow in a dedicated test with the setting off.
  • appium:grantPermissions style options exist in recent versions for more precise control; consult the driver docs.
  • System popups such as "App not responding" can be dismissed by the driver's settings; keep these rare by keeping builds healthy.

Speed and stability

  • appium:newCommandTimeout: how long to wait between commands before ending the session.
  • appium:uiautomator2ServerLaunchTimeout and appium:uiautomator2ServerInstallTimeout: how long to wait for the on-device server. Raise them for slow CI emulators.
  • appium:adbExecTimeout: timeout for adb commands, in milliseconds.
  • appium:skipServerInstallation: do not reinstall the UiAutomator2 server APKs when they are already present. Saves several seconds per session on a stable device.
  • appium:skipDeviceInitialization: skip device checks and setup when you manage the device yourself.
  • appium:disableWindowAnimation: turn off animations, which makes tests faster and less flaky.
  • appium:ignoreUnimportantViews: build a smaller accessibility tree, which can speed up queries but hides some elements.
  • appium:allowInvisibleElements and appium:enableMultiWindows: reveal elements normally filtered out.

Settings are not capabilities

The driver also has settings (like waitForIdleTimeout and waitForSelectorTimeout), changed during a session with the updateSettings command rather than at start. Capabilities fix the session's shape; settings tune its behavior while it runs, which makes them useful for slow screens.

Python
driver.update_settings({"waitForIdleTimeout": 100, "actionAcknowledgmentTimeout": 100})
print(driver.get_settings())

A realistic capability set

JSON
{
  "platformName": "Android",
  "appium:automationName": "UiAutomator2",
  "appium:udid": "emulator-5554",
  "appium:app": "/builds/shop-debug.apk",
  "appium:autoGrantPermissions": true,
  "appium:newCommandTimeout": 180,
  "appium:disableWindowAnimation": true,
  "appium:uiautomator2ServerLaunchTimeout": 60000
}

Validate an Android capability set

The stand-in encodes the rules above: you need an app or the package and activity pair; fullReset and noReset conflict; and with several devices a udid is needed. It is a stand-in that mirrors the guidance, not the driver's own validation.

JS Stand-in: Android capability checker

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Which reset mode?

Reset choices change both speed and test independence. The stand-in estimates the startup cost of each mode in an illustrative model: the seconds are made-up round numbers, not measurements, but the ordering matches experience.

JS Stand-in: reset mode trade-offs

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Common Android session errors

  • "Neither app nor appPackage is set" style errors: you gave neither a file nor a package pair.
  • Activity never starts / "wait activity" timeout: wrong appActivity, or the launcher forwards elsewhere; add appWaitActivity.
  • Server install timeout on CI: raise the UiAutomator2 server timeouts or use a faster emulator image.
  • More than one device: give a udid.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which pair of capabilities launches an app that is already installed?

    appPackage names the application and appActivity the screen to start; together they launch an installed app.
  2. 2. What does appium:autoGrantPermissions do?

    It accepts the app's declared permissions up front, removing system dialogs from your flow.
  3. 3. Which reset option gives the cleanest state but is slowest?

    fullReset uninstalls and reinstalls, so every session starts like a new installation.
  4. 4. How do settings differ from capabilities?

    Capabilities define the session at creation; settings tune the driver's behavior while it is running.

Summary

  • Launch with appium:app, or appPackage plus appActivity for an installed app.
  • Pick a reset strategy deliberately: noReset, default, or fullReset.
  • autoGrantPermissions removes permission popups; test those flows separately.
  • Server timeouts, skipServerInstallation and disableWindowAnimation improve speed and stability.
  • Settings change behavior during a session; capabilities are fixed at creation.

Next: XCUITest Capabilities for iOS