Please note that the contents of this offline web site may be out of date. To access the most recent documentation visit the online version .
Note that links that point to online resources are green in color and will open in a new window.
We would love it if you could give us feedback about this material by filling this form (You have to be online to fill it)

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 Methods
void clearLastTraversedText ()
Clears the text from the last UI traversal event.
boolean click (int x, int y)
Perform a click at arbitrary coordinates specified by the user
boolean drag (int startX, int startY, int endX, int endY, int steps)
Performs a swipe from one coordinate to another coordinate.
void dumpWindowHierarchy (String fileName)
Helper method used for debugging to dump the current window's layout hierarchy.
void freezeRotation ()
Disables the sensors and freezes the device rotation at its current rotation state.
String getCurrentActivityName ()
This method is deprecated. The results returned should be considered unreliable
String getCurrentPackageName ()
Retrieves the name of the last package to report accessibility events.
int getDisplayHeight ()
Gets the height of the display, in pixels.
int getDisplayRotation ()
Returns the current rotation of the display, as defined in Surface
Point getDisplaySizeDp ()
Returns the display size in dp (device-independent pixel) The returned display size is adjusted per screen rotation.
int getDisplayWidth ()
Gets the width of the display, in pixels.
static UiDevice getInstance ()
Retrieves a singleton instance of UiDevice
String getLastTraversedText ()
Retrieves the text from the last UI traversal event received.
String getProductName ()
Retrieves the product name of the device.
boolean hasAnyWatcherTriggered ()
Checks if any registered UiWatcher have triggered.
boolean hasWatcherTriggered (String watcherName)
Checks if a specific registered UiWatcher has triggered.
boolean isNaturalOrientation ()
Check if the device is in its natural orientation.
boolean isScreenOn ()
Checks the power manager if the screen is ON.
boolean openNotification ()
Opens the notification shade.
boolean openQuickSettings ()
Opens the Quick Settings shade.
boolean pressBack ()
Simulates a short press on the BACK button.
boolean pressDPadCenter ()
Simulates a short press on the CENTER button.
boolean pressDPadDown ()
Simulates a short press on the DOWN button.
boolean pressDPadLeft ()
Simulates a short press on the LEFT button.
boolean pressDPadRight ()
Simulates a short press on the RIGHT button.
boolean pressDPadUp ()
Simulates a short press on the UP button.
boolean pressDelete ()
Simulates a short press on the DELETE key.
boolean pressEnter ()
Simulates a short press on the ENTER key.
boolean pressHome ()
Simulates a short press on the HOME button.
boolean pressKeyCode (int keyCode, int metaState)
Simulates a short press using a key code.
boolean pressKeyCode (int keyCode)
Simulates a short press using a key code.
boolean pressMenu ()
Simulates a short press on the MENU button.
boolean pressRecentApps ()
Simulates a short press on the Recent Apps button.
boolean pressSearch ()
Simulates a short press on the SEARCH button.
void registerWatcher (String name, UiWatcher watcher)
Registers a UiWatcher to run automatically when the testing framework is unable to find a match using a UiSelector .
void removeWatcher (String name)
Removes a previously registered UiWatcher .
void resetWatcherTriggers ()
Resets a UiWatcher that has been triggered.
void runWatchers ()
This method forces all registered watchers to run.
void setCompressedLayoutHeirarchy (boolean compressed)
Enables or disables layout hierarchy compression.
void setOrientationLeft ()
Simulates orienting the device to the left and also freezes rotation by disabling the sensors.
void setOrientationNatural ()
Simulates orienting the device into its natural orientation and also freezes rotation by disabling the sensors.
void setOrientationRight ()
Simulates orienting the device to the right and also freezes rotation by disabling the sensors.
void sleep ()
This method simply presses the power button if the screen is ON else it does nothing if the screen is already OFF.
boolean swipe (Point[] segments, int segmentSteps)
Performs a swipe between points in the Point array.
boolean swipe (int startX, int startY, int endX, int endY, int steps)
Performs a swipe from one coordinate to another using the number of steps to determine smoothness and speed.
boolean takeScreenshot (File storePath)
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 (File storePath, float scale, int quality)
Take a screenshot of current window and store it as PNG The screenshot is adjusted per screen rotation
void unfreezeRotation ()
Re-enables the sensors and un-freezes the device rotation allowing its contents to rotate with the device physical rotation.
void waitForIdle (long timeout)
Waits for the current application to idle.
void waitForIdle ()
Waits for the current application to idle.
boolean waitForWindowUpdate (String packageName, long timeout)
Waits for a window content update event to occur.
void wakeUp ()
This method simulates pressing the power button if the screen is OFF else it does nothing if the screen is already ON.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public void clearLastTraversedText ()

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

public boolean click (int x, int y)

Perform a click at arbitrary coordinates specified by the user

Parameters
x coordinate
y coordinate
Returns
  • true if the click succeeded else false

public boolean drag (int startX, int startY, int endX, int endY, int steps)

Performs a swipe from one coordinate to another coordinate. 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 X-axis value for the starting coordinate
startY Y-axis value for the starting coordinate
endX X-axis value for the ending coordinate
endY Y-axis value for the ending coordinate
steps is the number of steps for the swipe action
Returns
  • true if swipe is performed, false if the operation fails or the coordinates are invalid
Since
  • Android API Level 18

public void dumpWindowHierarchy (String fileName)

Helper method used for debugging to dump the current window's layout hierarchy. The file root location is /data/local/tmp

public void freezeRotation ()

Disables the sensors and freezes the device rotation at its current rotation state.

Throws
RemoteException
RemoteException

public String getCurrentActivityName ()

This method is deprecated.
The results returned should be considered unreliable

Retrieves the last activity to report accessibility events.

Returns
  • String name of activity

public String getCurrentPackageName ()

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

Returns
  • String name of package

public int getDisplayHeight ()

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

Returns
  • height in pixels or zero on failure

public int getDisplayRotation ()

Returns the current rotation of the display, as defined in Surface

Since
  • Android API Level 17

public Point getDisplaySizeDp ()

Returns the 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
  • a Point containing the display size in dp
Since
  • Android API Level 18

public int getDisplayWidth ()

Gets the width of the display, in pixels. The width and height details are reported based on the current orientation of the display.

Returns
  • width in pixels or zero on failure

public static UiDevice getInstance ()

Retrieves a singleton instance of UiDevice

Returns
  • UiDevice instance

public String getLastTraversedText ()

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
  • text of the last traversal event, else return an empty string

public String getProductName ()

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
  • product name of the device
Since
  • Android API Level 17

public boolean hasAnyWatcherTriggered ()

Checks if any registered UiWatcher have triggered. See registerWatcher(String, UiWatcher) See hasWatcherTriggered(String)

public boolean hasWatcherTriggered (String watcherName)

Checks if a specific registered UiWatcher has triggered. See registerWatcher(String, UiWatcher) . 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.

Returns
  • true if triggered else false

public boolean isNaturalOrientation ()

Check if the device is in its natural orientation. This is determined by checking if the orientation is at 0 or 180 degrees.

Returns
  • true if it is in natural orientation
Since
  • Android API Level 17

public boolean isScreenOn ()

Checks the power manager if the screen is ON.

Returns
  • true if the screen is ON else false
Throws
RemoteException
RemoteException

public boolean openNotification ()

Opens the notification shade.

Returns
  • true if successful, else return false
Since
  • Android API Level 18

public boolean openQuickSettings ()

Opens the Quick Settings shade.

Returns
  • true if successful, else return false
Since
  • Android API Level 18

public boolean pressBack ()

Simulates a short press on the BACK button.

Returns
  • true if successful, else return false

public boolean pressDPadCenter ()

Simulates a short press on the CENTER button.

Returns
  • true if successful, else return false

public boolean pressDPadDown ()

Simulates a short press on the DOWN button.

Returns
  • true if successful, else return false

public boolean pressDPadLeft ()

Simulates a short press on the LEFT button.

Returns
  • true if successful, else return false

public boolean pressDPadRight ()

Simulates a short press on the RIGHT button.

Returns
  • true if successful, else return false

public boolean pressDPadUp ()

Simulates a short press on the UP button.

Returns
  • true if successful, else return false

public boolean pressDelete ()

Simulates a short press on the DELETE key.

Returns
  • true if successful, else return false

public boolean pressEnter ()

Simulates a short press on the ENTER key.

Returns
  • true if successful, else return false

public boolean pressHome ()

Simulates a short press on the HOME button.

Returns
  • true if successful, else return false

public boolean pressKeyCode (int keyCode, int metaState)

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

Parameters
keyCode the key code of the event.
metaState an integer in which each bit set to 1 represents a pressed meta key
Returns
  • true if successful, else return false

public boolean pressKeyCode (int keyCode)

Simulates a short press using a key code. See KeyEvent

Returns
  • true if successful, else return false

public boolean pressMenu ()

Simulates a short press on the MENU button.

Returns
  • true if successful, else return false

public boolean pressRecentApps ()

Simulates a short press on the Recent Apps button.

Returns
  • true if successful, else return false
Throws
RemoteException
RemoteException

public boolean pressSearch ()

Simulates a short press on the SEARCH button.

Returns
  • true if successful, else return false

public void registerWatcher (String name, UiWatcher watcher)

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

Parameters
name to register the UiWatcher
watcher UiWatcher

public void removeWatcher (String name)

Removes a previously registered UiWatcher . See registerWatcher(String, UiWatcher)

Parameters
name used to register the UiWatcher

public void resetWatcherTriggers ()

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(String, UiWatcher)

public void runWatchers ()

This method forces all registered watchers to run. See registerWatcher(String, UiWatcher)

public void setCompressedLayoutHeirarchy (boolean compressed)

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 true to enable compression; else, false to disable
Since
  • Android API Level 18

public void setOrientationLeft ()

Simulates orienting the device to the left and also freezes rotation by disabling the sensors. If you want to un-freeze the rotation and re-enable the sensors see unfreezeRotation() .

Throws
RemoteException
RemoteException
Since
  • Android API Level 17

public void setOrientationNatural ()

Simulates orienting the device into its natural orientation and also freezes rotation by disabling the sensors. If you want to un-freeze the rotation and re-enable the sensors see unfreezeRotation() .

Throws
RemoteException
RemoteException
Since
  • Android API Level 17

public void setOrientationRight ()

Simulates orienting the device to the right and also freezes rotation by disabling the sensors. If you want to un-freeze the rotation and re-enable the sensors see unfreezeRotation() .

Throws
RemoteException
RemoteException
Since
  • Android API Level 17

public void sleep ()

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

Throws
RemoteException
RemoteException

public boolean swipe (Point[] segments, int segmentSteps)

Performs a swipe between points in the Point array. 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 is Point array containing at least one Point object
segmentSteps steps to inject between two Points
Returns
  • true on success

public boolean swipe (int startX, int startY, int endX, int endY, int steps)

Performs a swipe from one coordinate to another 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
steps is the number of move steps sent to the system
Returns
  • false if the operation fails or the coordinates are invalid

public boolean takeScreenshot (File storePath)

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 where the PNG should be written to
Returns
  • true if screen shot is created successfully, false otherwise
Since
  • Android API Level 17

public boolean takeScreenshot (File storePath, float scale, int quality)

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

Parameters
storePath where the PNG should be written to
scale scale the screenshot down if needed; 1.0f for original size
quality quality of the PNG compression; range: 0-100
Returns
  • true if screen shot is created successfully, false otherwise
Since
  • Android API Level 17

public void unfreezeRotation ()

Re-enables the sensors and un-freezes the device rotation allowing its contents to rotate with the device physical rotation. During a test execution, it is best to keep the device frozen in a specific orientation until the test case execution has completed.

Throws
RemoteException

public void waitForIdle (long timeout)

Waits for the current application to idle.

Parameters
timeout in milliseconds

public void waitForIdle ()

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

public boolean waitForWindowUpdate (String packageName, long timeout)

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 the specified window package name (can be null ). If null , a window update from any front-end window will end the wait
timeout the timeout for the wait
Returns
  • true if a window update occurred, false if timeout has elapsed or if the current window does not have the specified package name

public void wakeUp ()

This method simulates pressing the power button if the screen is OFF else it does nothing if the screen is already ON. If the screen was OFF and it just got turned ON, this method will insert a 500ms delay to allow the device time to wake up and accept input.

Throws
RemoteException
RemoteException