androidx.test.uiautomator

fun uiAutomator(block: UiAutomatorTestScope.() -> Unit): Unit

Main entry point for ui automator tests. It creates a UiAutomatorTestScope in which a test can be defined.

Example:

@Test
fun myTest() = uiAutomator {

    startActivity(MyActivity::class.java)

    onElement { id == "button" }.click()

    onElement { id == "nested_elements" }
        .apply {
            onElement { text == "First Level" }
            onElement { text == "Second Level" }
            onElement { text == "Third Level" }
        }
}

fun UiDevice.activeWindow(): AccessibilityWindowInfo

Returns the active window.

fun AccessibilityNodeInfo.boundsInScreen(): Rect

Returns the bounds of this node in screen coordinates. This method is a shortcut for AccessibilityNodeInfo.getBoundsInScreen.

fun AccessibilityNodeInfo.children(
    block: (AccessibilityNodeInfo) -> Boolean = { true }
): List<AccessibilityNodeInfo>

Returns all the immediate children of this node. To return all the descendants (including children of children , children of children of children and so on use[ AccessibilityNodeInfo.descendants.

fun AccessibilityNodeInfo.descendants(
    filterBlock: (AccessibilityNodeInfo) -> Boolean = { true }
): List<AccessibilityNodeInfo>

Performs a DFS on the accessibility tree starting from this node and returns all the descendants discovered recursively. Optionally a filter can be specified. Note that this differs from AccessibilityNodeInfo.children() because this will return also children of children, children of children of children and so on.

fun AccessibilityNodeInfo.isClass(cls: Class<*>): Boolean

Returns whether this node class name is the same of the given class.

Usage:

onElement { isClass(Button::class.java) }.click()

fun AccessibilityNodeInfo.onElement(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2

Performs a DFS on the accessibility tree starting from this node and returns the first node matching the given block. The node is returned as an UiObject2 that allows interacting with it. If the requested node doesn't exist, a androidx.test.uiautomator.ElementNotFoundException is thrown. Internally it works searching periodically every pollIntervalMs.

Example:

node.onElement { textAsString == "Search" }.click()

fun AccessibilityWindowInfo.onElement(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2

Performs a DFS on the accessibility tree starting from the root node of this window and returns the first node matching the given block. The node is returned as an UiObject2 that allows interacting with it. If the requested node doesn't exist, a ElementNotFoundException is thrown.

Example:

onElement { textAsString == "Search" }.click()

fun UiDevice.onElement(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2

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. If the requested node doesn't exist, a ElementNotFoundException is thrown. Internally it works searching periodically every pollIntervalMs.

Example:

uiDevice.onElement { textAsString == "Search" }.click()

fun UiObject2.onElement(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2

Performs a DFS on the accessibility tree starting from the node associated to this UiObject2 and returns the first node matching the given block. The node is returned as an UiObject2 that allows interacting with it. If the requested node doesn't exist, a ElementNotFoundException is thrown. Internally it works searching periodically every pollIntervalMs.

Example:

onElement { textAsString == "Search" }.click()

fun AccessibilityNodeInfo.onElementOrNull(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2?

Performs a DFS on the accessibility tree starting from this node and returns the first node matching the given block. The node is returned as an UiObject2 that allows interacting with it. If the requested node doesn't exist, null is returned. Internally it works searching periodically every pollIntervalMs.

Example:

node.onElement { textAsString == "Search" }.click()

fun AccessibilityWindowInfo.onElementOrNull(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2?

Performs a DFS on the accessibility tree starting from the root node of this window and returns the first node matching the given block. The node is returned as an UiObject2 that allows interacting with it. If the requested node doesn't exist, null is returned. Internally it works searching periodically every pollIntervalMs.

Example:

onElement { textAsString == "Search" }.click()

fun UiDevice.onElementOrNull(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2?

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. If the requested node doesn't exist, null is returned. Internally it works searching periodically every pollIntervalMs.

Example:

uiDevice.onElement { textAsString == "Search" }.click()

fun UiObject2.onElementOrNull(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2?

Performs a DFS on the accessibility tree starting from the node associated to this UiObject2 and returns the first node matching the given block. The node is returned as an UiObject2 that allows interacting with it. If the requested node doesn't exist, null is returned. Internally it works searching periodically every pollIntervalMs.

Example:

onElement { textAsString == "Search" }.click()

fun AccessibilityNodeInfo.onElements(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): List<UiObject2>

Performs a DFS on the accessibility tree starting from this node and returns all the nodes matching the given block. This method stops waiting as soon as a single node with the given condition is returned. The nodes returned are UiObject2 that allow interacting with them. Internally it works searching periodically every pollIntervalMs.

Example:

node.onElements { className == Button::class.java.name }

If multiple nodes are expected but they appear at different times, it's recommended to call androidx.test.uiautomator.waitForStable before, to ensure any operation is complete.

fun AccessibilityWindowInfo.onElements(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): List<UiObject2>

Performs a DFS on the accessibility tree starting from the root node of this window and returns all the nodes matching the given block. This method stops waiting as soon as a single node with the given condition is returned. The nodes returned are UiObject2 that allow interacting with them. Internally it works searching periodically every pollIntervalMs.

Example:

node.onElements { className == Button::class.java.name }

If multiple nodes are expected but they appear at different times, it's recommended to call androidx.test.uiautomator.waitForStable before, to ensure any operation is complete.

fun UiDevice.onElements(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): List<UiObject2>

Performs a DFS on the accessibility tree starting from this node and returns all the nodes matching the given block. This method stops waiting as soon as a single node with the given condition is returned. The nodes returned are UiObject2 that allow interacting with them. Internally it works searching periodically every pollIntervalMs.

Example:

node.onElements { className == Button::class.java.name }

If multiple nodes are expected but they appear at different times, it's recommended to call androidx.test.uiautomator.waitForStable before, to ensure any operation is complete.

fun UiObject2.onElements(
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): List<UiObject2>

Performs a DFS on the accessibility tree starting from the node associated to this UiObject2 and returns all the nodes matching the given block. This method stops waiting as soon as a single node with the given condition is returned. The nodes returned are UiObject2 that allow interacting with them. Internally it works searching periodically every pollIntervalMs.

Example:

node.onElements { isClass(Button::class.java) }

If multiple nodes are expected but they appear at different times, it's recommended to call androidx.test.uiautomator.waitForStable before, to ensure any operation is complete.

fun UiDevice.pressDelete(count: Int): Unit

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

fun Bitmap.saveToFile(
    file: File,
    compressFormat: Bitmap.CompressFormat = Bitmap.CompressFormat.JPEG,
    quality: Int = 100
): Boolean

Utility function to save a bitmap onto the given file.

fun Bitmap.saveToFile(
    parcelFileDescriptor: ParcelFileDescriptor,
    compressFormat: Bitmap.CompressFormat = Bitmap.CompressFormat.JPEG,
    quality: Int = 100
): Boolean

Utility function to save a bitmap onto the given parcelFileDescriptor.

fun UiObject2.scrollToElement(
    direction: Direction,
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2

Keeps scrolling until the given block condition is satisfied or until the given timeoutMs. Throws a ElementNotFoundException if the condition is not satisfied at the end of the timeout.

Example:

onElement { isScrollable }.scrollToElement(Direction.DOWN) { id == "button" }.click()

fun UiObject2.scrollToElementOrNull(
    direction: Direction,
    timeoutMs: Long = 10000,
    pollIntervalMs: Long = 100,
    block: AccessibilityNodeInfo.() -> Boolean
): UiObject2

Keeps scrolling until the given block condition is satisfied or until the given timeoutMs. Returns null if the condition is not satisfied at the end of the timeout.

Example:

onElement { isScrollable }.scrollToElement(Direction.DOWN) { id == "button" }.click()

fun AccessibilityNodeInfo.siblings(
    filterBlock: (AccessibilityNodeInfo) -> Boolean = { true }
): List<AccessibilityNodeInfo>

Returns all the siblings of the this node.

fun AccessibilityNodeInfo.simpleViewResourceName(): String?

Returns this node's element id resource name without the resource namespace, i.e. only the portion after the "/" character. If the element id is not specified, then it returns null.

fun AccessibilityNodeInfo.takeScreenshot(): Bitmap

Takes a screenshot of the screen that contains this node and cuts only the area covered by it.

fun AccessibilityWindowInfo.takeScreenshot(): Bitmap

Takes a screenshot of the screen that contains this window and cuts only the area covered by it.

fun UiObject2.takeScreenshot(): Bitmap

Takes a screenshot of the screen that contains the accessibility node associated to this UiObject2 and cuts only the area covered by it.

fun AccessibilityNodeInfo.textAsString(): String?

Returns this node's text as a string. This should always be preferred to AccessibilityNodeInfo.text that instead returns a CharSequence, that might be either a String or a android.text.SpannableString. If a text is not specified, then it returns null.

Usage:

onElement { textAsString() == "Some text" }.click()

fun UiDevice.type(text: String): Unit

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.

fun UiDevice.waitForAppToBeVisible(
    appPackageName: String,
    timeoutMs: Long = 10000
): Boolean

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.

fun AccessibilityWindowInfo.waitForRoot(
    timeoutMs: Long = 10000,
    sleepIntervalMs: Long = 100,
    clearCache: Boolean = true
): AccessibilityNodeInfo

Waits for the root node to become available in this window.

fun UiDevice.waitForRootInActiveWindow(
    timeoutMs: Long = 10000,
    sleepIntervalMs: Long = 100,
    clearCache: Boolean = true
): AccessibilityNodeInfo

Waits for the root node to become available in this window.

fun AccessibilityNodeInfo.waitForStable(
    stableTimeoutMs: Long = 3000,
    stableIntervalMs: Long = 500,
    stablePollIntervalMs: Long = 50,
    requireStableScreenshot: Boolean = true
): StableResult

Waits for the node 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.

fun AccessibilityWindowInfo.waitForStable(
    stableTimeoutMs: Long = 3000,
    stableIntervalMs: Long = 500,
    stablePollIntervalMs: Long = 50,
    requireStableScreenshot: Boolean = true
): StableResult

Waits for the root node of this 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.

fun UiObject2.waitForStable(
    stableTimeoutMs: Long = 3000,
    stableIntervalMs: Long = 500,
    stablePollIntervalMs: Long = 50,
    requireStableScreenshot: Boolean = true
): StableResult

Waits for the node 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.

fun UiDevice.waitForStableInActiveWindow(
    stableTimeoutMs: Long = 3000,
    stableIntervalMs: Long = 500,
    stablePollIntervalMs: Long = 50,
    requireStableScreenshot: Boolean = true
): StableResult

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.

fun UiDevice.windows(): List<AccessibilityWindowInfo>

Returns all the windows on all the displays.