class UiDevice


UiDevice provides access to state information about the device. You can also use this class to simulate user actions on the device, such as pressing the d-pad or pressing the Home and Menu buttons.

Summary

Public functions

Unit

Clears the text from the last UI traversal event.

Boolean
click(x: Int, y: Int)

Perform a click at arbitrary coordinates on the default display specified by the user.

Boolean
drag(startX: Int, startY: Int, endX: Int, endY: Int, steps: Int)

Performs a swipe from one coordinate to another coordinate on the default display.

Unit

Dumps every window's layout hierarchy to a java.io.File in XML format.

Unit

This function is deprecated.

Use dumpWindowHierarchy or dumpWindowHierarchy instead.

Unit

Dumps every window's layout hierarchy to an java.io.OutputStream in XML format.

String
@Discouraged(message = "Can be useful for simple commands, but lacks support for proper error" + " handling, input data, or complex commands (quotes, pipes) that can be obtained " + "from UiAutomation#executeShellCommandRwe or similar utilities.")
executeShellCommand(cmd: String)

Executes a shell command using shell user identity, and return the standard output in string.

UiObject2!

Returns the first object to match the selector criteria, or null if no matching objects are found.

UiObject

Returns a UiObject which represents a view that matches the specified selector criteria.

(Mutable)List<UiObject2!>

Returns all objects that match the selector criteria.

Unit

Freezes the default display rotation at its current state.

Unit
@RequiresApi(value = 30)
freezeRotation(displayId: Int)

Freezes the rotation of the display with displayId at its current state.

String!

This function is deprecated.

The results returned should be considered unreliable

String!

Retrieves the name of the last package to report accessibility events.

@Px Int

Gets the height of the default display, in pixels.

@Px Int
getDisplayHeight(displayId: Int)

Gets the height of the display with displayId, in pixels.

Int
Int
getDisplayRotation(displayId: Int)
Point

Returns the default display size in dp (device-independent pixel).

@Px Int

Gets the width of the default display, in pixels.

@Px Int
getDisplayWidth(displayId: Int)

Gets the width of the display with displayId, in pixels.

java-static UiDevice

This function is deprecated.

Should use getInstance instead.

java-static UiDevice
getInstance(instrumentation: Instrumentation)

Retrieves a singleton instance of UiDevice.

String!

Retrieves the text from the last UI traversal event received.

String!

Retrieves the default launcher package name.

String

Retrieves the product name of the device.

Boolean

Checks if any registered UiWatcher have triggered.

Boolean
hasObject(selector: BySelector)

Returns whether there is a match for the given selector criteria.

Boolean
hasWatcherTriggered(watcherName: String?)

Checks if a specific registered UiWatcher has triggered.

Boolean
Boolean

Checks the power manager if the default display is ON.

Boolean

Opens the notification shade.

Boolean

Opens the Quick Settings shade.

U!
<U> performActionAndWait(
    action: Runnable,
    condition: EventCondition<U!>,
    timeout: Long
)

Performs the provided action and waits for the condition to be met.

Boolean

Simulates a short press on the BACK button.

Boolean

Simulates a short press on the CENTER button.

Boolean

Simulates a short press on the DOWN button.

Boolean

Simulates a short press on the LEFT button.

Boolean

Simulates a short press on the RIGHT button.

Boolean

Simulates a short press on the UP button.

Boolean

Simulates a short press on the DELETE key.

Boolean

Simulates a short press on the ENTER key.

Boolean

Simulates a short press on the HOME button.

Boolean
pressKeyCode(keyCode: Int)

Simulates a short press using a key code.

Boolean
pressKeyCode(keyCode: Int, metaState: Int)

Simulates a short press using a key code.

Boolean

Presses one or more keys.

Boolean
pressKeyCodes(keyCodes: IntArray, metaState: Int)

Presses one or more keys.

Boolean

Simulates a short press on the MENU button.

Boolean

Simulates a short press on the Recent Apps button.

Boolean

Simulates a short press on the SEARCH button.

Unit
registerWatcher(name: String?, watcher: UiWatcher?)

Registers a UiWatcher to run automatically when the testing framework is unable to find a match using a UiSelector.

Unit

Removes a previously registered UiWatcher.

Unit

Resets a UiWatcher that has been triggered.

Unit

This method forces all registered watchers to run.

Unit

This function is deprecated.

Typo in function name, should use setCompressedLayoutHierarchy instead.

Unit

Enables or disables layout hierarchy compression.

Unit

Orients the default display to its landscape orientation (width >= height) and freezes rotation.

Unit
@RequiresApi(value = 30)
setOrientationLandscape(displayId: Int)

Orients the display with displayId to its landscape orientation (width >= height) and freezes rotation.

Unit

Orients the default display to the left and freezes rotation.

Unit
@RequiresApi(value = 30)
setOrientationLeft(displayId: Int)

Orients the display with displayId to the left and freezes rotation.

Unit

Orients the default display to its natural orientation and freezes rotation.

Unit
@RequiresApi(value = 30)
setOrientationNatural(displayId: Int)

Orients the display with displayId to its natural orientation and freezes rotation .

Unit

Orients the default display to its portrait orientation (height >= width) and freezes rotation.

Unit
@RequiresApi(value = 30)
setOrientationPortrait(displayId: Int)

Orients the display with displayId to its portrait orientation (height >= width) and freezes rotation.

Unit

Orients the default display to the right and freezes rotation.

Unit
@RequiresApi(value = 30)
setOrientationRight(displayId: Int)

Orients the display with displayId to the right and freezes rotation.

Unit

This method simply presses the power button if the default display is ON, else it does nothing if the default display is already OFF.

Boolean
swipe(segments: Array<Point!>, segmentSteps: Int)

Performs a swipe between points in the Point array on the default display.

Boolean
swipe(startX: Int, startY: Int, endX: Int, endY: Int, steps: Int)

Performs a swipe from one coordinate to another on the default display using the number of steps to determine smoothness and speed.

Boolean
takeScreenshot(storePath: File)

Take a screenshot of current window and store it as PNG Default scale of 1.0f (original size) and 90% quality is used The screenshot is adjusted per screen rotation

Boolean
takeScreenshot(storePath: File, scale: Float, quality: Int)

Take a screenshot of current window and store it as PNG The screenshot is adjusted per screen rotation

Unit

Un-freezes the default display rotation allowing its contents to rotate with its physical rotation.

Unit
@RequiresApi(value = 30)
unfreezeRotation(displayId: Int)

Un-freezes the rotation of the display with displayId allowing its contents to rotate with its physical rotation.

U!
<U> wait(condition: Condition<UiDevice!, U!>, timeout: Long)

Waits for given the condition to be met.

U!
<U> wait(condition: SearchCondition<U!>, timeout: Long)

Waits for given the condition to be met.

Unit

Waits for the current application to idle.

Unit
waitForIdle(timeout: Long)

Waits for the current application to idle.

Boolean
waitForWindowUpdate(packageName: String?, timeout: Long)

Waits for a window content update event to occur.

Unit

This method simulates pressing the power button if the default display is OFF, else it does nothing if the default display is already ON.

Public functions

clearLastTraversedText

Added in 2.2.0
fun clearLastTraversedText(): Unit

Clears the text from the last UI traversal event. See getLastTraversedText.

click

Added in 2.2.0
fun click(x: Int, y: Int): Boolean

Perform a click at arbitrary coordinates on the default display specified by the user.

Parameters
x: Int

coordinate

y: Int

coordinate

Returns
Boolean

true if the click succeeded else false

drag

Added in 2.2.0
fun drag(startX: Int, startY: Int, endX: Int, endY: Int, steps: Int): Boolean

Performs a swipe from one coordinate to another coordinate on the default display. You can control the smoothness and speed of the swipe by specifying the number of steps. Each step execution is throttled to 5 milliseconds per step, so for a 100 steps, the swipe will take around 0.5 seconds to complete.

Parameters
startX: Int

X-axis value for the starting coordinate

startY: Int

Y-axis value for the starting coordinate

endX: Int

X-axis value for the ending coordinate

endY: Int

Y-axis value for the ending coordinate

steps: Int

is the number of steps for the swipe action

Returns
Boolean

true if swipe is performed, false if the operation fails or the coordinates are invalid

dumpWindowHierarchy

Added in 2.2.0
fun dumpWindowHierarchy(dest: File): Unit

Dumps every window's layout hierarchy to a java.io.File in XML format.

Parameters
dest: File

The file in which to store the window hierarchy information.

Throws
java.io.IOException

if an I/O error occurs

dumpWindowHierarchy

Added in 2.2.0
Deprecated in 2.2.0
fun dumpWindowHierarchy(fileName: String): Unit

Dumps every window's layout hierarchy to a file in XML format.

Parameters
fileName: String

The file path in which to store the window hierarchy information. Relative file paths are stored the application's internal private storage location.

dumpWindowHierarchy

Added in 2.2.0
fun dumpWindowHierarchy(out: OutputStream): Unit

Dumps every window's layout hierarchy to an java.io.OutputStream in XML format.

Parameters
out: OutputStream

The output stream that the window hierarchy information is written to.

Throws
java.io.IOException

if an I/O error occurs

executeShellCommand

Added in 2.3.0
@Discouraged(message = "Can be useful for simple commands, but lacks support for proper error"
            + " handling, input data, or complex commands (quotes, pipes) that can be obtained "
            + "from UiAutomation#executeShellCommandRwe or similar utilities.")
fun executeShellCommand(cmd: String): String

Executes a shell command using shell user identity, and return the standard output in string.

Calling function with large amount of output will have memory impacts, and the function call will block if the command executed is blocking.

Parameters
cmd: String

the command to run

Returns
String

the standard output of the command

Throws
java.io.IOException

if an I/O error occurs while reading output

findObject

Added in 2.2.0
fun findObject(selector: BySelector): UiObject2!

Returns the first object to match the selector criteria, or null if no matching objects are found.

findObject

Added in 2.2.0
fun findObject(selector: UiSelector): UiObject

Returns a UiObject which represents a view that matches the specified selector criteria.

Parameters
selector: UiSelector
Returns
UiObject

UiObject object

findObjects

Added in 2.2.0
fun findObjects(selector: BySelector): (Mutable)List<UiObject2!>

Returns all objects that match the selector criteria.

freezeRotation

Added in 2.2.0
fun freezeRotation(): Unit

Freezes the default display rotation at its current state.

freezeRotation

Added in 2.3.0
@RequiresApi(value = 30)
fun freezeRotation(displayId: Int): Unit

Freezes the rotation of the display with displayId at its current state.

Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.

Throws
java.lang.IllegalArgumentException

when the display with displayId is not accessible.

See also
getDisplayId

getCurrentActivityName

Added in 2.2.0
Deprecated in 2.2.0
fun getCurrentActivityName(): String!

Retrieves the last activity to report accessibility events.

Returns
String!

String name of activity

getCurrentPackageName

Added in 2.2.0
fun getCurrentPackageName(): String!

Retrieves the name of the last package to report accessibility events.

Returns
String!

String name of package

getDisplayHeight

Added in 2.2.0
fun getDisplayHeight(): @Px Int

Gets the height of the default display, in pixels. The size is adjusted based on the current orientation of the display.

Returns
@Px Int

height in pixels

getDisplayHeight

Added in 2.3.0
fun getDisplayHeight(displayId: Int): @Px Int

Gets the height of the display with displayId, in pixels. The size is adjusted based on the current orientation of the display.

Parameters
displayId: Int

the display ID. Use getDisplayId to get the ID.

Returns
@Px Int

height in pixels

Throws
java.lang.IllegalArgumentException

when the display with displayId is not accessible.

getDisplayRotation

Added in 2.2.0
fun getDisplayRotation(): Int
Returns
Int

the current rotation of the default display

See also
getRotation

getDisplayRotation

Added in 2.3.0
fun getDisplayRotation(displayId: Int): Int
Returns
Int

the current rotation of the display with displayId

Throws
java.lang.IllegalArgumentException

when the display with displayId is not accessible.

getDisplaySizeDp

Added in 2.2.0
fun getDisplaySizeDp(): Point

Returns the default display size in dp (device-independent pixel).

The returned display size is adjusted per screen rotation. Also this will return the actual size of the screen, rather than adjusted per system decorations (like status bar).

Returns
Point

a Point containing the display size in dp

See also
density

getDisplayWidth

Added in 2.2.0
fun getDisplayWidth(): @Px Int

Gets the width of the default display, in pixels. The size is adjusted based on the current orientation of the display.

Returns
@Px Int

width in pixels

getDisplayWidth

Added in 2.3.0
fun getDisplayWidth(displayId: Int): @Px Int

Gets the width of the display with displayId, in pixels. The size is adjusted based on the current orientation of the display.

Parameters
displayId: Int

the display ID. Use getDisplayId to get the ID.

Returns
@Px Int

width in pixels

Throws
java.lang.IllegalArgumentException

when the display with displayId is not accessible.

getInstance

Added in 2.2.0
Deprecated in 2.2.0
java-static fun getInstance(): UiDevice

Retrieves a singleton instance of UiDevice

Returns
UiDevice

UiDevice instance

getInstance

Added in 2.2.0
java-static fun getInstance(instrumentation: Instrumentation): UiDevice

Retrieves a singleton instance of UiDevice. A new instance will be created if instrumentation is also new.

Returns
UiDevice

UiDevice instance

getLastTraversedText

Added in 2.2.0
fun getLastTraversedText(): String!

Retrieves the text from the last UI traversal event received. You can use this method to read the contents in a WebView container because the accessibility framework fires events as each text is highlighted. You can write a test to perform directional arrow presses to focus on different elements inside a WebView, and call this method to get the text from each traversed element. If you are testing a view container that can return a reference to a Document Object Model (DOM) object, your test should use the view's DOM instead.

Returns
String!

text of the last traversal event, else return an empty string

getLauncherPackageName

Added in 2.2.0
fun getLauncherPackageName(): String!

Retrieves the default launcher package name.

As of Android 11 (API level 30), apps must declare the packages and intents they intend to query. To use this method, an app will need to include the following in its manifest:

<queries>
  <intent>
    <action android:name="android.intent.action.MAIN"/>
    <category android:name="android.intent.category.HOME"/>
  </intent>
</queries>
Returns
String!

package name of the default launcher

getProductName

Added in 2.2.0
fun getProductName(): String

Retrieves the product name of the device. This method provides information on what type of device the test is running on. This value is the same as returned by invoking #adb shell getprop ro.product.name.

Returns
String

product name of the device

hasAnyWatcherTriggered

Added in 2.2.0
fun hasAnyWatcherTriggered(): Boolean

Checks if any registered UiWatcher have triggered. See registerWatcher See hasWatcherTriggered

hasObject

Added in 2.2.0
fun hasObject(selector: BySelector): Boolean

Returns whether there is a match for the given selector criteria.

hasWatcherTriggered

Added in 2.2.0
fun hasWatcherTriggered(watcherName: String?): Boolean

Checks if a specific registered UiWatcher has triggered. See registerWatcher. If a UiWatcher runs and its checkForCondition call returned true, then the UiWatcher is considered triggered. This is helpful if a watcher is detecting errors from ANR or crash dialogs and the test needs to know if a UiWatcher has been triggered.

Parameters
watcherName: String?
Returns
Boolean

true if triggered else false

isNaturalOrientation

Added in 2.2.0
fun isNaturalOrientation(): Boolean
Returns
Boolean

true if default display is in its natural or flipped (180 degrees) orientation

isScreenOn

Added in 2.2.0
fun isScreenOn(): Boolean

Checks the power manager if the default display is ON.

Returns
Boolean

true if the screen is ON else false

openNotification

Added in 2.2.0
fun openNotification(): Boolean

Opens the notification shade.

Returns
Boolean

true if successful, else return false

openQuickSettings

Added in 2.2.0
fun openQuickSettings(): Boolean

Opens the Quick Settings shade.

Returns
Boolean

true if successful, else return false

performActionAndWait

Added in 2.3.0
fun <U> performActionAndWait(
    action: Runnable,
    condition: EventCondition<U!>,
    timeout: Long
): U!

Performs the provided action and waits for the condition to be met.

Parameters
action: Runnable

The Runnable action to perform.

condition: EventCondition<U!>

The EventCondition to evaluate.

timeout: Long

Maximum amount of time to wait in milliseconds.

Returns
U!

The final result returned by the condition.

pressBack

Added in 2.2.0
fun pressBack(): Boolean

Simulates a short press on the BACK button.

Returns
Boolean

true if successful, else return false

pressDPadCenter

Added in 2.2.0
fun pressDPadCenter(): Boolean

Simulates a short press on the CENTER button.

Returns
Boolean

true if successful, else return false

pressDPadDown

Added in 2.2.0
fun pressDPadDown(): Boolean

Simulates a short press on the DOWN button.

Returns
Boolean

true if successful, else return false

pressDPadLeft

Added in 2.2.0
fun pressDPadLeft(): Boolean

Simulates a short press on the LEFT button.

Returns
Boolean

true if successful, else return false

pressDPadRight

Added in 2.2.0
fun pressDPadRight(): Boolean

Simulates a short press on the RIGHT button.

Returns
Boolean

true if successful, else return false

pressDPadUp

Added in 2.2.0
fun pressDPadUp(): Boolean

Simulates a short press on the UP button.

Returns
Boolean

true if successful, else return false

pressDelete

Added in 2.2.0
fun pressDelete(): Boolean

Simulates a short press on the DELETE key.

Returns
Boolean

true if successful, else return false

pressEnter

Added in 2.2.0
fun pressEnter(): Boolean

Simulates a short press on the ENTER key.

Returns
Boolean

true if successful, else return false

pressHome

Added in 2.2.0
fun pressHome(): Boolean

Simulates a short press on the HOME button.

Returns
Boolean

true if successful, else return false

pressKeyCode

Added in 2.2.0
fun pressKeyCode(keyCode: Int): Boolean

Simulates a short press using a key code. See KeyEvent

Returns
Boolean

true if successful, else return false

pressKeyCode

Added in 2.2.0
fun pressKeyCode(keyCode: Int, metaState: Int): Boolean

Simulates a short press using a key code. See KeyEvent.

Parameters
keyCode: Int

the key code of the event.

metaState: Int

an integer in which each bit set to 1 represents a pressed meta key

Returns
Boolean

true if successful, else return false

pressKeyCodes

Added in 2.3.0
fun pressKeyCodes(keyCodes: IntArray): Boolean

Presses one or more keys. For example, you can simulate taking a screenshot on the device by pressing both the power and volume down keys.

pressKeyCodes(new int[]{KeyEvent.KEYCODE_POWER, KeyEvent.KEYCODE_VOLUME_DOWN})
Parameters
keyCodes: IntArray

array of key codes.

Returns
Boolean

true if successful, else return false

See also
KeyEvent

pressKeyCodes

Added in 2.3.0
fun pressKeyCodes(keyCodes: IntArray, metaState: Int): Boolean

Presses one or more keys. For example, you can simulate taking a screenshot on the device by pressing both the power and volume down keys.

pressKeyCodes(new int[]{KeyEvent.KEYCODE_POWER, KeyEvent.KEYCODE_VOLUME_DOWN})
Parameters
keyCodes: IntArray

array of key codes.

metaState: Int

an integer in which each bit set to 1 represents a pressed meta key

Returns
Boolean

true if successful, else return false

See also
KeyEvent

pressMenu

Added in 2.2.0
fun pressMenu(): Boolean

Simulates a short press on the MENU button.

Returns
Boolean

true if successful, else return false

pressRecentApps

Added in 2.2.0
fun pressRecentApps(): Boolean

Simulates a short press on the Recent Apps button.

Returns
Boolean

true if successful, else return false

pressSearch

Added in 2.2.0
fun pressSearch(): Boolean

Simulates a short press on the SEARCH button.

Returns
Boolean

true if successful, else return false

registerWatcher

Added in 2.2.0
fun registerWatcher(name: String?, watcher: UiWatcher?): Unit

Registers a UiWatcher to run automatically when the testing framework is unable to find a match using a UiSelector. See runWatchers

Parameters
name: String?

to register the UiWatcher

watcher: UiWatcher?

UiWatcher

removeWatcher

Added in 2.2.0
fun removeWatcher(name: String?): Unit

Removes a previously registered UiWatcher. See registerWatcher

Parameters
name: String?

used to register the UiWatcher

resetWatcherTriggers

Added in 2.2.0
fun resetWatcherTriggers(): Unit

Resets a UiWatcher that has been triggered. If a UiWatcher runs and its checkForCondition call returned true, then the UiWatcher is considered triggered. See registerWatcher

runWatchers

Added in 2.2.0
fun runWatchers(): Unit

This method forces all registered watchers to run. See registerWatcher

setCompressedLayoutHeirarchy

Added in 2.2.0
Deprecated in 2.3.0
fun setCompressedLayoutHeirarchy(compressed: Boolean): Unit

Enables or disables layout hierarchy compression. If compression is enabled, the layout hierarchy derived from the Acessibility framework will only contain nodes that are important for uiautomator testing. Any unnecessary surrounding layout nodes that make viewing and searching the hierarchy inefficient are removed.

Parameters
compressed: Boolean

true to enable compression; else, false to disable

setCompressedLayoutHierarchy

Added in 2.3.0
fun setCompressedLayoutHierarchy(compressed: Boolean): Unit

Enables or disables layout hierarchy compression. If compression is enabled, the layout hierarchy derived from the Accessibility framework will only contain nodes that are important for uiautomator testing. Any unnecessary surrounding layout nodes that make viewing and searching the hierarchy inefficient are removed.

Parameters
compressed: Boolean

true to enable compression; else, false to disable

setOrientationLandscape

Added in 2.3.0
fun setOrientationLandscape(): Unit

Orients the default display to its landscape orientation (width >= height) and freezes rotation. Use unfreezeRotation to un-freeze the rotation.

setOrientationLandscape

Added in 2.3.0
@RequiresApi(value = 30)
fun setOrientationLandscape(displayId: Int): Unit

Orients the display with displayId to its landscape orientation (width >= height) and freezes rotation. Use unfreezeRotation to un-freeze the rotation.

Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.

Throws
java.lang.IllegalArgumentException

when the display with displayId is not accessible.

See also
getDisplayId

setOrientationLeft

Added in 2.2.0
fun setOrientationLeft(): Unit

Orients the default display to the left and freezes rotation. Use unfreezeRotation to un-freeze the rotation.

Note: This rotation is relative to the natural orientation which depends on the device type (e.g. phone vs. tablet). Consider using setOrientationPortrait and setOrientationLandscape.

setOrientationLeft

Added in 2.3.0
@RequiresApi(value = 30)
fun setOrientationLeft(displayId: Int): Unit

Orients the display with displayId to the left and freezes rotation. Use unfreezeRotation to un-freeze the rotation.

Note: This rotation is relative to the natural orientation which depends on the device type (e.g. phone vs. tablet). Consider using setOrientationPortrait and setOrientationLandscape.

Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.

Throws
java.lang.IllegalArgumentException

when the display with displayId is not accessible.

See also
getDisplayId

setOrientationNatural

Added in 2.2.0
fun setOrientationNatural(): Unit

Orients the default display to its natural orientation and freezes rotation. Use unfreezeRotation to un-freeze the rotation.

Note: The natural orientation depends on the device type (e.g. phone vs. tablet). Consider using setOrientationPortrait and setOrientationLandscape.

setOrientationNatural

Added in 2.3.0
@RequiresApi(value = 30)
fun setOrientationNatural(displayId: Int): Unit

Orients the display with displayId to its natural orientation and freezes rotation . Use unfreezeRotation to un-freeze the rotation.

Note: The natural orientation depends on the device type (e.g. phone vs. tablet). Consider using setOrientationPortrait and setOrientationLandscape.

Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.

Throws
java.lang.IllegalArgumentException

when the display with displayId is not accessible.

See also
getDisplayId

setOrientationPortrait

Added in 2.3.0
fun setOrientationPortrait(): Unit

Orients the default display to its portrait orientation (height >= width) and freezes rotation. Use unfreezeRotation to un-freeze the rotation.

setOrientationPortrait

Added in 2.3.0
@RequiresApi(value = 30)
fun setOrientationPortrait(displayId: Int): Unit

Orients the display with displayId to its portrait orientation (height >= width) and freezes rotation. Use unfreezeRotation to un-freeze the rotation.

Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.

Throws
java.lang.IllegalArgumentException

when the display with displayId is not accessible.

See also
getDisplayId

setOrientationRight

Added in 2.2.0
fun setOrientationRight(): Unit

Orients the default display to the right and freezes rotation. Use unfreezeRotation to un-freeze the rotation.

Note: This rotation is relative to the natural orientation which depends on the device type (e.g. phone vs. tablet). Consider using setOrientationPortrait and setOrientationLandscape.

setOrientationRight

Added in 2.3.0
@RequiresApi(value = 30)
fun setOrientationRight(displayId: Int): Unit

Orients the display with displayId to the right and freezes rotation. Use unfreezeRotation to un-freeze the rotation.

Note: This rotation is relative to the natural orientation which depends on the device type (e.g. phone vs. tablet). Consider using setOrientationPortrait and setOrientationLandscape.

Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.

Throws
java.lang.IllegalArgumentException

when the display with displayId is not accessible.

See also
getDisplayId

sleep

Added in 2.2.0
fun sleep(): Unit

This method simply presses the power button if the default display is ON, else it does nothing if the default display is already OFF.

swipe

Added in 2.2.0
fun swipe(segments: Array<Point!>, segmentSteps: Int): Boolean

Performs a swipe between points in the Point array on the default display. Each step execution is throttled to 5ms per step. So for a 100 steps, the swipe will take about 1/2 second to complete.

Parameters
segments: Array<Point!>

is Point array containing at least one Point object

segmentSteps: Int

steps to inject between two Points

Returns
Boolean

true on success

swipe

Added in 2.2.0
fun swipe(startX: Int, startY: Int, endX: Int, endY: Int, steps: Int): Boolean

Performs a swipe from one coordinate to another on the default display using the number of steps to determine smoothness and speed. Each step execution is throttled to 5ms per step. So for a 100 steps, the swipe will take about 1/2 second to complete.

Parameters
startX: Int

X-axis value for the starting coordinate

startY: Int

Y-axis value for the starting coordinate

endX: Int

X-axis value for the ending coordinate

endY: Int

Y-axis value for the ending coordinate

steps: Int

is the number of move steps sent to the system

Returns
Boolean

false if the operation fails or the coordinates are invalid

takeScreenshot

Added in 2.2.0
fun takeScreenshot(storePath: File): Boolean

Take a screenshot of current window and store it as PNG Default scale of 1.0f (original size) and 90% quality is used The screenshot is adjusted per screen rotation

Parameters
storePath: File

where the PNG should be written to

Returns
Boolean

true if screen shot is created successfully, false otherwise

takeScreenshot

Added in 2.2.0
fun takeScreenshot(storePath: File, scale: Float, quality: Int): Boolean

Take a screenshot of current window and store it as PNG The screenshot is adjusted per screen rotation

Parameters
storePath: File

where the PNG should be written to

scale: Float

scale the screenshot down if needed; 1.0f for original size

quality: Int

quality of the PNG compression; range: 0-100

Returns
Boolean

true if screen shot is created successfully, false otherwise

unfreezeRotation

Added in 2.2.0
fun unfreezeRotation(): Unit

Un-freezes the default display rotation allowing its contents to rotate with its physical rotation. During testing, it is best to keep the default display frozen in a specific orientation.

Note: Need to wait a short period for the rotation animation to complete before performing another operation.

unfreezeRotation

Added in 2.3.0
@RequiresApi(value = 30)
fun unfreezeRotation(displayId: Int): Unit

Un-freezes the rotation of the display with displayId allowing its contents to rotate with its physical rotation. During testing, it is best to keep the display frozen in a specific orientation.

Note: Need to wait a short period for the rotation animation to complete before performing another operation.

Note: Some secondary displays don't have rotation sensors and therefore won't respond to this method.

Note: Only works on Android API level 30 (R) or above, where multi-display is officially supported.

See also
getDisplayId

wait

Added in 2.3.0
fun <U> wait(condition: Condition<UiDevice!, U!>, timeout: Long): U!

Waits for given the condition to be met.

Parameters
condition: Condition<UiDevice!, U!>

The Condition to evaluate.

timeout: Long

Maximum amount of time to wait in milliseconds.

Returns
U!

The final result returned by the condition, or null if the condition was not met before the timeout.

wait

Added in 2.3.0
fun <U> wait(condition: SearchCondition<U!>, timeout: Long): U!

Waits for given the condition to be met.

Parameters
condition: SearchCondition<U!>

The SearchCondition to evaluate.

timeout: Long

Maximum amount of time to wait in milliseconds.

Returns
U!

The final result returned by the condition, or null if the condition was not met before the timeout.

waitForIdle

Added in 2.2.0
fun waitForIdle(): Unit

Waits for the current application to idle. Default wait timeout is 10 seconds

waitForIdle

Added in 2.2.0
fun waitForIdle(timeout: Long): Unit

Waits for the current application to idle.

Parameters
timeout: Long

in milliseconds

waitForWindowUpdate

Added in 2.2.0
fun waitForWindowUpdate(packageName: String?, timeout: Long): Boolean

Waits for a window content update event to occur. If a package name for the window is specified, but the current window does not have the same package name, the function returns immediately.

Parameters
packageName: String?

the specified window package name (can be null). If null, a window update from any front-end window will end the wait

timeout: Long

the timeout for the wait

Returns
Boolean

true if a window update occurred, false if timeout has elapsed or if the current window does not have the specified package name

wakeUp

Added in 2.2.0
fun wakeUp(): Unit

This method simulates pressing the power button if the default display is OFF, else it does nothing if the default display is already ON.

If the default display was OFF and it just got turned ON, this method will insert a 500ms delay for the device to wake up and accept input.