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)
Android APIs
public final class

UiAutomation

extends Object
java.lang.Object
   ↳ android.app.UiAutomation

Class Overview

Class for interacting with the device's UI by simulation user actions and introspection of the screen content. It relies on the platform accessibility APIs to introspect the screen and to perform some actions on the remote view tree. It also allows injecting of arbitrary raw input events simulating user interaction with keyboards and touch devices. One can think of a UiAutomation as a special type of AccessibilityService which does not provide hooks for the service life cycle and exposes other APIs that are useful for UI test automation.

The APIs exposed by this class are low-level to maximize flexibility when developing UI test automation tools and libraries. Generally, a UiAutomation client should be using a higher-level library or implement high-level functions. For example, performing a tap on the screen requires construction and injecting of a touch down and up events which have to be delivered to the system by a call to injectInputEvent(InputEvent, boolean) .

The APIs exposed by this class operate across applications enabling a client to write tests that cover use cases spanning over multiple applications. For example, going to the settings application to change a setting and then interacting with another application whose behavior depends on that setting.

Summary

Nested Classes
interface UiAutomation.AccessibilityEventFilter Listener for filtering accessibility events. 
interface UiAutomation.OnAccessibilityEventListener Listener for observing the AccessibilityEvent stream. 
Constants
int ROTATION_FREEZE_0 Rotation constant: Freeze rotation to 0 degrees (natural orientation)
int ROTATION_FREEZE_180 Rotation constant: Freeze rotation to 180 degrees .
int ROTATION_FREEZE_270 Rotation constant: Freeze rotation to 270 degrees .
int ROTATION_FREEZE_90 Rotation constant: Freeze rotation to 90 degrees .
int ROTATION_FREEZE_CURRENT Rotation constant: Freeze rotation to its current state.
int ROTATION_UNFREEZE Rotation constant: Unfreeze rotation (rotating the device changes its rotation state).
Public Methods
AccessibilityEvent executeAndWaitForEvent ( Runnable command, UiAutomation.AccessibilityEventFilter filter, long timeoutMillis)
Executes a command and waits for a specific accessibility event up to a given wait timeout.
AccessibilityNodeInfo getRootInActiveWindow ()
Gets the root AccessibilityNodeInfo in the active window.
final AccessibilityServiceInfo getServiceInfo ()
Gets the an AccessibilityServiceInfo describing this UiAutomation.
boolean injectInputEvent ( InputEvent event, boolean sync)
A method for injecting an arbitrary input event.
final boolean performGlobalAction (int action)
Performs a global action.
void setOnAccessibilityEventListener ( UiAutomation.OnAccessibilityEventListener listener)
Sets a callback for observing the stream of AccessibilityEvent s.
boolean setRotation (int rotation)
Sets the device rotation.
void setRunAsMonkey (boolean enable)
Sets whether this UiAutomation to run in a "monkey" mode.
final void setServiceInfo ( AccessibilityServiceInfo info)
Sets the AccessibilityServiceInfo that describes how this UiAutomation will be handled by the platform accessibility layer.
Bitmap takeScreenshot ()
Takes a screenshot.
void waitForIdle (long idleTimeoutMillis, long globalTimeoutMillis)
Waits for the accessibility event stream to become idle, which is not to have received an accessibility event within idleTimeoutMillis .
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int ROTATION_FREEZE_0

Added in API level 18

Rotation constant: Freeze rotation to 0 degrees (natural orientation)

Constant Value: 0 (0x00000000)

public static final int ROTATION_FREEZE_180

Added in API level 18

Rotation constant: Freeze rotation to 180 degrees .

Constant Value: 2 (0x00000002)

public static final int ROTATION_FREEZE_270

Added in API level 18

Rotation constant: Freeze rotation to 270 degrees .

Constant Value: 3 (0x00000003)

public static final int ROTATION_FREEZE_90

Added in API level 18

Rotation constant: Freeze rotation to 90 degrees .

Constant Value: 1 (0x00000001)

public static final int ROTATION_FREEZE_CURRENT

Added in API level 18

Rotation constant: Freeze rotation to its current state.

Constant Value: -1 (0xffffffff)

public static final int ROTATION_UNFREEZE

Added in API level 18

Rotation constant: Unfreeze rotation (rotating the device changes its rotation state).

Constant Value: -2 (0xfffffffe)

Public Methods

public AccessibilityEvent executeAndWaitForEvent ( Runnable command, UiAutomation.AccessibilityEventFilter filter, long timeoutMillis)

Executes a command and waits for a specific accessibility event up to a given wait timeout. To detect a sequence of events one can implement a filter that keeps track of seen events of the expected sequence and returns true after the last event of that sequence is received.

Note: It is caller's responsibility to recycle the returned event.

Parameters
command The command to execute.
filter Filter that recognizes the expected event.
timeoutMillis The wait timeout in milliseconds.
Throws
TimeoutException If the expected event is not received within the timeout.

public AccessibilityNodeInfo getRootInActiveWindow ()

Gets the root AccessibilityNodeInfo in the active window.

Returns
  • The root info.

public final AccessibilityServiceInfo getServiceInfo ()

Gets the an AccessibilityServiceInfo describing this UiAutomation. This method is useful if one wants to change some of the dynamically configurable properties at runtime.

Returns
  • The accessibility service info.
See Also

public boolean injectInputEvent ( InputEvent event, boolean sync)

A method for injecting an arbitrary input event.

Note: It is caller's responsibility to recycle the event.

Parameters
event The event to inject.
sync Whether to inject the event synchronously.
Returns
  • Whether event injection succeeded.

public final boolean performGlobalAction (int action)

Performs a global action. Such an action can be performed at any moment regardless of the current application or user location in that application. For example going back, going home, opening recents, etc.

Parameters
action The action to perform.
Returns
  • Whether the action was successfully performed.
See Also

public void setOnAccessibilityEventListener ( UiAutomation.OnAccessibilityEventListener listener)

Sets a callback for observing the stream of AccessibilityEvent s.

Parameters
listener The callback.

public boolean setRotation (int rotation)

Sets the device rotation. A client can freeze the rotation in desired state or freeze the rotation to its current state or unfreeze the rotation (rotating the device changes its rotation state).

Parameters
rotation The desired rotation.
Returns
  • Whether the rotation was set successfully.
See Also

public void setRunAsMonkey (boolean enable)

Sets whether this UiAutomation to run in a "monkey" mode. Applications can query whether they are executed in a "monkey" mode, i.e. run by a test framework, and avoid doing potentially undesirable actions such as calling 911 or posting on public forums etc.

Parameters
enable whether to run in a "monkey" mode or not. Default is not.
See Also

public final void setServiceInfo ( AccessibilityServiceInfo info)

Sets the AccessibilityServiceInfo that describes how this UiAutomation will be handled by the platform accessibility layer.

Parameters
info The info.
See Also

public Bitmap takeScreenshot ()

Takes a screenshot.

Returns
  • The screenshot bitmap on success, null otherwise.

public void waitForIdle (long idleTimeoutMillis, long globalTimeoutMillis)

Waits for the accessibility event stream to become idle, which is not to have received an accessibility event within idleTimeoutMillis . The total time spent to wait for an idle accessibility event stream is bounded by the globalTimeoutMillis .

Parameters
idleTimeoutMillis The timeout in milliseconds between two events to consider the device idle.
globalTimeoutMillis The maximal global timeout in milliseconds in which to wait for an idle state.
Throws
TimeoutException If no idle state was detected within globalTimeoutMillis.