sodcalculator

10 Tech How-To

Android UI Automator: How to Automate UI Tests

Guide 10-54679 · Updated · Step by step

To automate UI tests with Android UI Automator, you write a JUnit test that uses the UiDevice and UiObject APIs to find and interact with on-screen elements, then run it on a connected device or emulator. This framework is designed for black-box testing—it does not need your app’s source code or internal structure, making it ideal for testing across multiple apps and system UI. Below is a complete guide covering setup, writing tests, running them, and common pitfalls.

Background: What Is UI Automator?

UI Automator is a testing framework included in the Android SDK since API level 18 (Android 4.3). It works by inspecting the accessibility tree of the current screen, which contains all visible UI elements and their properties (text, content description, bounds, etc.). This allows you to write tests that interact with any app—even ones you do not own—as long as the device is in a known state.

It contrasts with Espresso, which is white-box and requires the app’s source code, and with Appium, which is a cross-platform tool that uses the same accessibility principles but with a different API. UI Automator is the only official Android framework that can interact with system UI (like the status bar) and with other apps during a test.

How UI Automator Works

The core components are:

  • UiDevice – represents the device state. You can press buttons (home, back, menu), take screenshots, and find UI objects.
  • UiObject – represents a UI element. You can click, long-click, drag, set text, and check properties.
  • UiSelector – a query that describes how to find a UiObject (by text, resource ID, content description, class, etc.).
  • UiCollection and UiScrollable – helpers for working with lists and scrollable views.

When you call device.findObject(selector), the framework waits for the UI to become idle (up to a default timeout of 10 seconds) and then returns a UiObject that points to the first matching element. If no element matches, the UiObject is considered “not found” and any interaction throws a UiObjectNotFoundException.

Setting Up Your Test Environment

Before writing tests, you need to add the dependencies to your app’s build.gradle file:

androidTestImplementation 'androidx.test.uiautomator:uiautomator:2.3.0'

You also need to set the test runner to AndroidJUnitRunner in the default config:

testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"

UI Automator tests are instrumentation tests, so they run on the device or emulator. You can run them with the standard connectedAndroidTest Gradle task or from Android Studio by right-clicking the test class and selecting “Run”.

Writing Your First UI Automator Test

Here is a minimal test that opens the Settings app and checks that the Wi-Fi toggle exists:

import androidx.test.uiautomator.UiDevice;
import androidx.test.uiautomator.UiObject;
import androidx.test.uiautomator.UiSelector;
import androidx.test.platform.app.InstrumentationRegistry;
import org.junit.Test;

public class SettingsTest {
    @Test
    public void testWifiToggle() throws Exception {
        UiDevice device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation());
        device.pressHome();
        device.pressRecentApps();
        // Launch Settings via the app drawer (simplified)
        device.findObject(new UiSelector().text("Settings")).click();
        // Wait for the screen to load
        device.waitForIdle(3000);
        // Find the Wi-Fi toggle by resource ID
        UiObject wifiToggle = device.findObject(new UiSelector().resourceId("com.android.settings:id/switch_wifi"));
        assertTrue(wifiToggle.exists());
    }
}

The test uses UiSelector to locate elements. Common selector methods include:

  • .text("string") – matches exact text.
  • .textContains("substring") – matches partial text.
  • .resourceId("package:id/name") – matches by resource ID.
  • .contentDescription("desc") – matches content description (important for accessibility).
  • .className("android.widget.Button") – matches by class name.

You can chain selectors to narrow down matches, e.g., new UiSelector().className("android.widget.ListView").childSelector(new UiSelector().text("Wi-Fi")).

Interacting with Complex UI Elements

Many screens have scrollable lists or need gestures. UI Automator provides UiScrollable for scrolling:

UiScrollable list = new UiScrollable(new UiSelector().scrollable(true));
list.scrollTextIntoView("Bluetooth");
UiObject bluetooth = device.findObject(new UiSelector().text("Bluetooth"));
bluetooth.click();

For dragging, use UiObject.dragTo() or UiDevice.swipe(). To enter text into an EditText, use setText() after clicking the field. For drop-down menus, use UiObject.click() and then select an option from the resulting list.

One common pitfall is that UI Automator cannot interact with elements that are not visible on the screen. If an element is off-screen, you must scroll to it first. Also, animations can cause flakiness—use device.waitForIdle() or device.wait(Until.hasObject(selector), timeout) to wait for the UI to settle.

Common Problems and How to Fix Them

  • Element not found: The selector is too strict or the element is not visible. Use UiSelector().textContains() or check the UI hierarchy with device.dumpWindowHierarchy() (saves an XML file to the device).
  • Test flakiness: Often caused by animations or network delays. Increase wait times using device.wait(Until.hasObject(selector), 5000) instead of fixed sleeps.
  • Cannot interact with WebView content: UI Automator can only see the accessibility tree, which may not expose WebView internals. Use UiDevice.findObject(UiSelector().className("android.webkit.WebView")) and then use UiObject.setText() or UiObject.click() on child elements if they are exposed.
  • Test fails on different screen sizes: Use resource IDs and content descriptions instead of coordinates. If you must use coordinates, compute them relative to the screen size using device.getDisplayWidth() and getDisplayHeight().
  • Permission dialogs: UI Automator can handle system dialogs because it can see the entire screen. Write a helper method to click “Allow” when a specific dialog appears.

Comparing UI Automator with Espresso and Appium

Choose the right tool based on your needs:

  • UI Automator – Best for cross-app and system UI tests, black-box testing, and when you do not have the app’s source. It is fast and integrated with Android Studio.
  • Espresso – Best for white-box testing of your own app. It is more reliable because it synchronizes with the UI thread, but it cannot interact with other apps or system UI.
  • Appium – Best for cross-platform (iOS + Android) testing. It uses a WebDriver protocol and is slower, but it allows writing tests in many languages (Java, Python, JS).

Many teams combine Espresso for in-app logic and UI Automator for end-to-end scenarios that involve multiple apps (e.g., login with Google, sharing to another app).

Best Practices for Reliable UI Tests

  1. Use unique resource IDs or content descriptions in your app to make selectors stable.
  2. Always wait for elements to appear before interacting—use device.wait(Until.hasObject(selector), timeout).
  3. Keep tests independent: reset the app state in @Before or use @After to clear data.
  4. Run tests on a device with animations disabled (Settings > Developer Options > set all animation scales to 0) to reduce flakiness.
  5. Take screenshots on failure using device.takeScreenshot() in an @After method to help debug.

Frequently Asked Questions

Can UI Automator test any app?

Yes, as long as the app renders its UI in a way that is exposed to the accessibility system. Most native Android apps work, but some custom views or games that draw directly to the canvas may not expose individual elements. In those cases, you may need to use coordinate-based interactions or switch to a different tool.

How do I find the resource ID of an element?

Use the Layout Inspector in Android Studio, or run adb shell uiautomator dump to get an XML file of the current screen. The XML contains resource IDs, text, and bounds for every visible element.

Why does my test fail when the screen is locked?

UI Automator cannot interact with the lock screen. Make sure the device is unlocked before the test starts. You can use device.wakeUp() and device.pressMenu() to unlock if swipe is not required, but for secure locks you must disable them for testing.

Can I run UI Automator tests on multiple devices simultaneously?

Yes, you can use Gradle managed devices or a cloud testing service like Firebase Test Lab. Each device runs the test independently, but you need to ensure your test code does not rely on a specific device state.

Is UI Automator still supported in 2025?

Yes, the framework is still part of the AndroidX Test library, and Google continues to maintain it. However, for new projects, consider using Compose UI testing if you are building with Jetpack Compose, as UI Automator does not work well with Compose’s semantics tree. For classic View-based apps, UI Automator remains a solid choice.

What is the difference between UiObject and BySelector?

UiObject is the older API, while BySelector is a newer, more flexible API introduced in version 2.0. BySelector allows you to use lambdas and more complex conditions. Both are still supported, but BySelector is recommended for new tests because it is more concise and less error-prone.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →