UiAutomatorTestScope


public class UiAutomatorTestScope


A UiAutomator scope that allows to easily access UiAutomator api and utils class.

Summary

Protected constructors

Public methods

final @NonNull AccessibilityNodeInfo

Returns the active window root node.

final void

Clears the instrumentation test target app data.

final @NonNull UiDevice
final @NonNull Instrumentation
final @NonNull UiAutomation
final @NonNull UiObject2
onView(
    long timeoutMs,
    long pollIntervalMs,
    @ExtensionFunctionType @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)

Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given block.

final UiObject2
onViewOrNull(
    long timeoutMs,
    long pollIntervalMs,
    @ExtensionFunctionType @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)

Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given block.

final @NonNull List<@NonNull UiObject2>
onViews(
    long timeoutMs,
    long pollIntervalMs,
    @ExtensionFunctionType @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)

Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given block.

final boolean

Press the back key.

final void
pressDelete(int count)

Similar to type but presses the delete key for the given count times.

final boolean

Press the enter key.

final boolean

Press the home key.

final void

Starts an activity with the given class.

final void
startActivity(@NonNull String packageName, @NonNull String activityName)

Starts an activity with the given packageName and activityName.

final void

Starts the instrumentation test target app using the target app package name.

final void
startApp(@NonNull String packageName)

Starts the app with the given packageName.

final void

Starts the given intent.

final void

Types the given text string simulating key press through Instrumentation.sendKeySync.

final void

Unregisters all the watchers previously registered with watchFor.

final boolean
waitForAppToBeVisible(@NonNull String appPackageName, long timeoutMs)

Waits for an application to become visible.

final @NonNull StableResult
waitForStableInActiveWindow(
    long stableTimeoutMs,
    long stableIntervalMs,
    long stablePollIntervalMs,
    boolean requireStableScreenshot
)

Waits for the root node of the active window to become stable.

final @NonNull WatcherRegistration
<T extends Object> watchFor(
    @NonNull ScopedUiWatcher<@NonNull T> watcher,
    @ExtensionFunctionType @NonNull Function1<@NonNull T, Unit> block
)

Registers a watcher for this androidx.test.uiautomator.UiAutomatorTestScope to handle unexpected UI elements.

final @NonNull List<@NonNull AccessibilityNodeInfo>

Returns all the window roots on all the displays.

final @NonNull List<@NonNull AccessibilityWindowInfo>

Returns all the windows on all the displays.

Protected constructors

UiAutomatorTestScope

Added in 2.4.0-alpha02
protected UiAutomatorTestScope()

Public methods

activeWindowRoot

Added in 2.4.0-alpha02
public final @NonNull AccessibilityNodeInfo activeWindowRoot()

Returns the active window root node. Note that calling this method after startApp, startActivity or startIntent without waiting for the app to be visible, will return the active window root at the time of starting the app, i.e. the root of the launcher if starting from there.

clearAppData

Added in 2.4.0-alpha02
public final void clearAppData()

Clears the instrumentation test target app data.

getDevice

Added in 2.4.0-alpha02
public final @NonNull UiDevice getDevice()

getInstrumentation

Added in 2.4.0-alpha02
public final @NonNull Instrumentation getInstrumentation()

getUiAutomation

Added in 2.4.0-alpha02
public final @NonNull UiAutomation getUiAutomation()

onView

Added in 2.4.0-alpha02
public final @NonNull UiObject2 onView(
    long timeoutMs,
    long pollIntervalMs,
    @ExtensionFunctionType @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)

Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given block. The node is returned as an UiObject2 that allows interacting with it. Internally it works searching periodically every pollIntervalMs.

Example:

onView { textAsString == "Search" }.click()
Parameters
long timeoutMs

a timeout to find the view that satisfies the given condition.

long pollIntervalMs

an interval to wait before rechecking the accessibility tree for updates.

@ExtensionFunctionType @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block

a block that specifies a condition on the node to find.

Returns
@NonNull UiObject2

a UiObject2 from a node that matches the given block condition.

onViewOrNull

Added in 2.4.0-alpha02
public final UiObject2 onViewOrNull(
    long timeoutMs,
    long pollIntervalMs,
    @ExtensionFunctionType @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)

Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given block. The node is returned as an UiObject2 that allows interacting with it. Internally it works searching periodically every pollIntervalMs.

Example:

onView { textAsString == "Search" }.click()
Parameters
long timeoutMs

a timeout to find the view that satisfies the given condition.

long pollIntervalMs

an interval to wait before rechecking the accessibility tree for updates.

@ExtensionFunctionType @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block

a block that specifies a condition on the node to find.

Returns
UiObject2

a UiObject2 from a node that matches the given block condition or null.

onViews

Added in 2.4.0-alpha02
public final @NonNull List<@NonNull UiObject2onViews(
    long timeoutMs,
    long pollIntervalMs,
    @ExtensionFunctionType @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block
)

Performs a DFS on the accessibility tree starting from the root node in the active window and returns the first node matching the given block. The node is returned as an UiObject2 that allows interacting with it. Internally it works searching periodically every pollIntervalMs.

Example:

node.onViews { isClass(Button::class.java) }
Parameters
long timeoutMs

a timeout to find the view that satisfies the given condition.

long pollIntervalMs

an interval to wait before rechecking the accessibility tree for updates.

@ExtensionFunctionType @NonNull Function1<@NonNull AccessibilityNodeInfo, @NonNull Boolean> block

a block that specifies a condition on the node to find.

Returns
@NonNull List<@NonNull UiObject2>

a list of UiObject2 from nodes that matches the given block condition.

pressBack

Added in 2.4.0-alpha02
public final boolean pressBack()

Press the back key.

pressDelete

Added in 2.4.0-alpha02
public final void pressDelete(int count)

Similar to type but presses the delete key for the given count times.

Parameters
int count

how many times the press delete key should be pressed.

pressEnter

Added in 2.4.0-alpha02
public final boolean pressEnter()

Press the enter key.

pressHome

Added in 2.4.0-alpha02
public final boolean pressHome()

Press the home key.

startActivity

Added in 2.4.0-alpha02
public final void startActivity(@NonNull Class<@NonNull ?> clazz)

Starts an activity with the given class.

Parameters
@NonNull Class<@NonNull ?> clazz

the class of the activity to start.

startActivity

Added in 2.4.0-alpha02
public final void startActivity(@NonNull String packageName, @NonNull String activityName)

Starts an activity with the given packageName and activityName.

Parameters
@NonNull String packageName

the app package name of the activity to start.

@NonNull String activityName

the name of the activity to start.

startApp

Added in 2.4.0-alpha02
public final void startApp()

Starts the instrumentation test target app using the target app package name.

startApp

Added in 2.4.0-alpha02
public final void startApp(@NonNull String packageName)

Starts the app with the given packageName.

Parameters
@NonNull String packageName

the package name of the app to start

startIntent

Added in 2.4.0-alpha02
public final void startIntent(@NonNull Intent intent)

Starts the given intent.

Parameters
@NonNull Intent intent

an intent to start

type

Added in 2.4.0-alpha02
public final void type(@NonNull String text)

Types the given text string simulating key press through Instrumentation.sendKeySync. This is similar to tapping the keys on a virtual keyboard and will trigger the same listeners in the target app, as opposed to AccessibilityNodeInfo.setText that programmaticaly sets the given text in the target node.

Parameters
@NonNull String text

the text to type.

unregisterWatchers

Added in 2.4.0-alpha02
public final void unregisterWatchers()

Unregisters all the watchers previously registered with watchFor.

waitForAppToBeVisible

Added in 2.4.0-alpha02
public final boolean waitForAppToBeVisible(@NonNull String appPackageName, long timeoutMs)

Waits for an application to become visible. Note that internally it checks if an accessibility node with the given appPackageName exists in the accessibility tree.

Parameters
@NonNull String appPackageName

the package name of the app to wait for. By default is the target app package name.

long timeoutMs

a timeout for the app to become visible.

Returns
boolean

whether the app became visible in the given timeout.

waitForStableInActiveWindow

Added in 2.4.0-alpha02
public final @NonNull StableResult waitForStableInActiveWindow(
    long stableTimeoutMs,
    long stableIntervalMs,
    long stablePollIntervalMs,
    boolean requireStableScreenshot
)

Waits for the root node of the active window to become stable.

A node is considered stable when it and its descendants have not changed over an interval of time. Optionally also the node image can be checked. Internally it works checking periodically that the internal properties of the node have not changed.

Parameters
long stableTimeoutMs

a timeout for the wait operation, to ensure not waiting forever for stability.

long stableIntervalMs

the interval during which the node should not be changing, in order to be considered stable.

long stablePollIntervalMs

specifies how often the ui should be checked for changes.

boolean requireStableScreenshot

specifies if also the bitmap of the node should not change over the specified stableIntervalMs. Note that this won't work with views that change constantly, like a video player.

Returns
@NonNull StableResult

a StableResult containing the latest acquired view hierarchy and screenshot, and a flag indicating if the node was stable before timeout.

watchFor

Added in 2.4.0-alpha02
public final @NonNull WatcherRegistration <T extends Object> watchFor(
    @NonNull ScopedUiWatcher<@NonNull T> watcher,
    @ExtensionFunctionType @NonNull Function1<@NonNull T, Unit> block
)

Registers a watcher for this androidx.test.uiautomator.UiAutomatorTestScope to handle unexpected UI elements. Internally this method uses the existing UiDevice.registerWatcher api. When the given ScopedUiWatcher.isVisible condition is satisfied, then the given block is executed. scope. This method returns a handler with the WatcherRegistration to unregister it before the block is complete. Note that this api helps with unexpected ui elements, such as system dialogs, and that for expected dialogs the onView api should be used.

Usage:

@Test fun myTest() = uiAutomator {

// Registers a watcher for a permission dialog.
watchFor(PermissionDialog) { clickAllow() }

// Registers a watcher for a custom dialog and unregisters it.
val registration = watchFor(MyDialog) { clickSomething() }
// Do something...
registration.unregister()
}
Parameters
@NonNull ScopedUiWatcher<@NonNull T> watcher

the dialog to watch for.

@ExtensionFunctionType @NonNull Function1<@NonNull T, Unit> block

a block to handle.

Returns
@NonNull WatcherRegistration

the dialog registration.

windowRoots

Added in 2.4.0-alpha02
public final @NonNull List<@NonNull AccessibilityNodeInfowindowRoots()

Returns all the window roots on all the displays.

windows

Added in 2.4.0-alpha02
public final @NonNull List<@NonNull AccessibilityWindowInfowindows()

Returns all the windows on all the displays.