Cross App Tests With Uiautomator

Cross-App Tests with UiAutomator — Drive System UI and Other Apps

UiAutomator is the only AndroidX test framework that can drive UI across process boundaries — Settings, the dialer, system notifications, another app's activity. Espresso refuses (InjectEventSecurityException) when an event would cross to a foreign window. UiAutomator works against the platform AccessibilityNodeInfo tree, so it sees every window. This skill encodes the modern BySelector / UiObject2 API, the singleton acquisition, the StaleObjectException recovery pattern, and the cross-app launch path.

When to use this skill

• The test must drive system UI (Settings, dialer, system notifications, quick settings, recents).
• The test spans the developer's app and another app (share sheet, contacts picker, camera).
• Espresso threw InjectEventSecurityException because the test reached a foreign window.
• The user reports StaleObjectException and is debugging cached-node lifetime.
• The user asks how to send the device home, press recents, or toggle airplane mode in a test.
• The user mixes BySelector and UiSelector in the same test and is confused which is current.

When NOT to use this skill

• The UI is entirely inside the developer's app — Espresso (Views) or Compose tests are faster and more reliable. See ../../espresso/writing-espresso-tests/SKILL.md for Views.
• The runner stack is not yet set up — start with ../../runner/running-instrumented-tests-with-androidjunit4/SKILL.md.
• The user only needs to push device-side state changes (animations off, intent stub) — see ../../../adb/control/injecting-input-and-state/SKILL.md.
• The test only needs to scrape logs after a run — see ../../../adb/observability/extracting-logs-with-logcat/SKILL.md.

Prerequisites

• Runner stack from ../../runner/running-instrumented-tests-with-androidjunit4/SKILL.md.
• androidTestImplementation("androidx.test.uiautomator:uiautomator:2.3.0").
• A real or virtual Android device with the accessibility_service available (the default).
• For Context.startActivity to a foreign package on API 30+, a <queries> entry in the test APK manifest naming the target package or intent action.

Workflow

• 1. Acquire UiDevice once per test, via the singleton with explicit instrumentation. The no-arg getInstance() is @Deprecated (R4 lines 56-58) — it throws IllegalStateException if not previously initialized:

import androidx.test.platform.app.InstrumentationRegistry
import androidx.test.uiautomator.UiDevice

private lateinit var device: UiDevice

@Before fun setUp() {
    device = UiDevice.getInstance(InstrumentationRegistry.getInstrumentation())
}

• 2. Send hard keys and global actions via UiDevice methods. Source: R4 lines 88-104.

device.pressBack()
device.pressHome()
device.pressMenu()
device.pressRecentApps()                                // GLOBAL_ACTION_RECENTS
device.pressKeyCode(KeyEvent.KEYCODE_VOLUME_DOWN)
device.openNotification()                                // GLOBAL_ACTION_NOTIFICATIONS
device.openQuickSettings()                               // GLOBAL_ACTION_QUICK_SETTINGS
device.wakeUp()                                          // power-on if off
device.sleep()                                           // power-off if on

• 3. Find UI elements with BySelector (modern) via the By factory. Selectors are immutable-ish builders; the package-private constructor enforces use of the static factories. Criteria are joined as implicit AND. Source: R4 lines 185-258.

import androidx.test.uiautomator.By

By.text("Submit")                              // exact, case-sensitive
By.textContains("ubmi")                        // case-sensitive substring
By.textMatches("Sub.*")                        // Pattern.compile regex
By.desc("Open menu")                           // content description
By.res("com.example.app", "submit_btn")        // package + res id
By.res("com.example.app:id/submit_btn")        // qualified res id
By.clazz("android.widget.Button")              // fully-qualified, or ".widget.Button" auto-prefixed with "android"
By.clazz(android.widget.Button::class.java)
By.pkg("com.android.settings")
By.depth(2)                                    // depth from window root
By.checkable(true)
By.hasChild(By.text("Inner"))                  // sugar for hasDescendant(child, 1)
By.hasDescendant(By.text("anywhere"))
By.hasParent(By.clazz("...LinearLayout"))
By.hasAncestor(By.res("...container"))

• 4. Resolve to UiObject2 via device.findObject(...) and act. findObject returns null when no match (NEVER throws). For interactions, prefer device.wait(Until.findObject(By...), timeoutMillis) so the lookup is robust to slow renders:

import androidx.test.uiautomator.Until

val submit = device.wait(Until.findObject(By.res("com.example", "submit")), 5_000)
    ?: error("Submit not found within 5s")

submit.click()
submit.longClick()
submit.setText("hello")
submit.clear()
submit.swipe(Direction.LEFT, 0.8f)            // percent ∈ [0,1]
submit.scroll(Direction.DOWN, 1.0f)
submit.scrollUntil(Direction.DOWN, Until.findObject(By.text("Bottom")))
submit.pinchOpen(0.5f)
submit.pinchClose(0.5f)

UiObject2 caches an AccessibilityNodeInfo. Each action calls getAccessibilityNodeInfo() which calls device.waitForIdle() then mCachedNode.refresh(); on failure it runs registered UiWatchers, retries once, and on a second failure throws StaleObjectException (R4 lines 281-286, 622-637).

• 5. Wait for asynchronous UI states with Until conditions. Three condition flavors per R4 lines 495-540:

// SearchCondition (consume the device tree)
device.wait(Until.hasObject(By.text("Loaded")), 5_000)
device.wait(Until.gone(By.text("Loading")), 5_000)
val obj: UiObject2? = device.wait(Until.findObject(By.text("OK")), 5_000)
val list: List<UiObject2>? = device.wait(Until.findObjects(By.clazz("...Button")), 3_000)

// UiObject2Condition (consume a UiObject2 — for state predicates)
val checked = button.wait(Until.checked(true), 5_000)

// EventCondition (consume AccessibilityEvents — for window transitions)
val newWindowFired = device.performActionAndWait(
    { button.click() }, Until.newWindow(), 10_000,
)

• 6. Recover from StaleObjectException by re-finding. StaleObjectException extends RuntimeException — unchecked, must be handled when holding a long-lived UiObject2:

fun clickRetry(selector: BySelector, timeoutMillis: Long = 5_000) {
    val obj = device.wait(Until.findObject(selector), timeoutMillis)
        ?: error("Not found: $selector")
    try {
        obj.click()
    } catch (e: StaleObjectException) {
        device.wait(Until.findObject(selector), timeoutMillis)?.click()
            ?: throw e
    }
}

Better: re-look-up before each interaction instead of holding a long-lived reference. Common causes: activity transition, Compose recomposition replacing semantic nodes, RecyclerView recycle, configuration change (R4 lines 639-645).

• 7. Launch foreign packages — prefer Context.startActivity over executeShellCommand. executeShellCommand is @Discouraged per R4 lines 147-151 (UiDevice.java:1432); the Javadoc recommends UiAutomation.executeShellCommandRwe for stdin/stderr. For routine app launches, use the in-process intent route plus a <queries> manifest entry on API 30+:

<!-- src/androidTest/AndroidManifest.xml -->
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <queries>
        <package android:name="com.android.settings" />
        <intent>
            <action android:name="android.settings.SETTINGS" />
        </intent>
    </queries>
    <!-- ... -->
</manifest>

val ctx = ApplicationProvider.getApplicationContext<Context>()
ctx.startActivity(
    Intent(android.provider.Settings.ACTION_WIFI_SETTINGS)
        .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP)
)
device.wait(Until.hasObject(By.pkg("com.android.settings").depth(0)), 10_000)

If the user really needs the shell route (e.g. a deep-link no Intent resolves):

device.executeShellCommand("am start -n com.android.settings/.Settings")
device.wait(Until.hasObject(By.pkg("com.android.settings")), 5_000)

• 8. Tune Configurator global timeouts when needed; restore on teardown. Settings are process-wide. Defaults (R4 lines 550-558): wait-for-idle 10s, wait-for-selector 10s (legacy UiObject only), action-acknowledgment 3s, scroll-event-wait 1s.

import androidx.test.uiautomator.Configurator

@Before fun setUp() {
    val c = Configurator.getInstance()
    originalIdle = c.waitForIdleTimeout
    c.waitForIdleTimeout = 5_000   // tighter for fast tests
}

@After fun tearDown() {
    Configurator.getInstance().waitForIdleTimeout = originalIdle
}

setKeyInjectionDelay is @Deprecated ("This parameter is no longer used (text is set directly rather than by key)." — R4 lines 575-577). Do not call it.

• 9. Recognize when to fall back to legacy UiSelector / UiObject. UiSelector re-resolves the node on every action via Configurator.getWaitForSelectorTimeout(), so it cannot go stale, but every call is more expensive and uses the checked UiObjectNotFoundException. The modern BySelector / UiObject2 is the recommended default. Use legacy only for interop with old test code or when re-resolution semantics are mandatory. R4 lines 594-619.

• 10. Never call findObject(By.text("...")) immediately after launch and assume it sees the target window. By.text matches whatever is on screen now, which may be a transient splash or the previous app. Always combine with By.pkg(...) or wait explicitly:

device.pressHome()
ctx.startActivity(Intent(Settings.ACTION_SETTINGS).addFlags(Intent.FLAG_ACTIVITY_NEW_TASK))
device.wait(Until.hasObject(By.pkg("com.android.settings")), 5_000)   // gate on package
device.wait(Until.findObject(By.text("Network & internet")), 5_000)?.click()

Patterns

Pattern: WRONG vs RIGHT — driving Settings without waiting on package transition

// WRONG
device.findObject(By.text("Settings")).click()
// WRONG because: at the moment of the call, By.text("Settings") matches whatever text reads
// "Settings" anywhere on the current screen — that might be a launcher tile, a notification,
// or a previous-app menu item. The test silently navigates to the wrong place.

// RIGHT
device.pressHome()
device.executeShellCommand("am start -a android.settings.SETTINGS")
device.wait(Until.hasObject(By.pkg("com.android.settings")), 5_000)
device.wait(Until.findObject(By.text("Network & internet")), 5_000)?.click()