public final class UiAutomation extends Object
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.
Modifier and Type | Class and Description |
---|---|
static interface |
UiAutomation.AccessibilityEventFilter
Listener for filtering accessibility events.
|
static interface |
UiAutomation.OnAccessibilityEventListener
Listener for observing the
AccessibilityEvent stream. |
Modifier and Type | Field and Description |
---|---|
static int |
FLAG_DONT_SUPPRESS_ACCESSIBILITY_SERVICES
UiAutomation supresses accessibility services by default.
|
static int |
ROTATION_FREEZE_0
Rotation constant: Freeze rotation to 0 degrees (natural orientation)
|
static int |
ROTATION_FREEZE_180
Rotation constant: Freeze rotation to 180 degrees .
|
static int |
ROTATION_FREEZE_270
Rotation constant: Freeze rotation to 270 degrees .
|
static int |
ROTATION_FREEZE_90
Rotation constant: Freeze rotation to 90 degrees .
|
static int |
ROTATION_FREEZE_CURRENT
Rotation constant: Freeze rotation to its current state.
|
static int |
ROTATION_UNFREEZE
Rotation constant: Unfreeze rotation (rotating the device changes its rotation state).
|
Constructor and Description |
---|
UiAutomation(Looper looper,
IUiAutomationConnection connection)
Creates a new instance that will handle callbacks from the accessibility
layer on the thread of the provided looper and perform requests for privileged
operations on the provided connection.
|
Modifier and Type | Method and Description |
---|---|
void |
clearWindowAnimationFrameStats()
Clears the window animation rendering statistics.
|
boolean |
clearWindowContentFrameStats(int windowId)
Clears the frame statistics for the content of a given window.
|
void |
connect()
Connects this UiAutomation to the accessibility introspection APIs with default flags.
|
void |
connect(int flags)
Connects this UiAutomation to the accessibility introspection APIs.
|
void |
destroy()
Destroy this UiAutomation.
|
void |
disconnect()
Disconnects this UiAutomation from the accessibility introspection APIs.
|
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.
|
ParcelFileDescriptor |
executeShellCommand(String command)
Executes a shell command.
|
AccessibilityNodeInfo |
findFocus(int focus)
Find the view that has the specified focus type.
|
int |
getConnectionId()
The id of the
IAccessibilityInteractionConnection for querying
the screen content. |
int |
getFlags()
Get the flags used to connect the service.
|
AccessibilityNodeInfo |
getRootInActiveWindow()
Gets the root
AccessibilityNodeInfo in the active window. |
AccessibilityServiceInfo |
getServiceInfo()
Gets the an
AccessibilityServiceInfo describing this UiAutomation. |
WindowAnimationFrameStats |
getWindowAnimationFrameStats()
Gets the window animation frame statistics.
|
WindowContentFrameStats |
getWindowContentFrameStats(int windowId)
Gets the frame statistics for a given window.
|
List<AccessibilityWindowInfo> |
getWindows()
Gets the windows on the screen.
|
boolean |
grantRuntimePermission(String packageName,
String permission,
UserHandle userHandle)
Grants a runtime permission to a package for a user.
|
boolean |
injectInputEvent(InputEvent event,
boolean sync)
A method for injecting an arbitrary input event.
|
boolean |
isDestroyed()
Reports if the object has been destroyed
|
boolean |
performGlobalAction(int action)
Performs a global action.
|
boolean |
revokeRuntimePermission(String packageName,
String permission,
UserHandle userHandle)
Revokes a runtime permission from a package for a user.
|
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.
|
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 . |
public static final int ROTATION_UNFREEZE
public static final int ROTATION_FREEZE_CURRENT
public static final int ROTATION_FREEZE_0
public static final int ROTATION_FREEZE_90
public static final int ROTATION_FREEZE_180
public static final int ROTATION_FREEZE_270
public static final int FLAG_DONT_SUPPRESS_ACCESSIBILITY_SERVICES
Instrumentation.getUiAutomation(int)
.public UiAutomation(Looper looper, IUiAutomationConnection connection)
looper
- The looper on which to execute accessibility callbacks.connection
- The connection for performing privileged operations.public void connect()
public void connect(int flags)
flags
- Any flags to apply to the automation as it gets connectedpublic int getFlags()
public void disconnect()
public int getConnectionId()
IAccessibilityInteractionConnection
for querying
the screen content. This is here for legacy purposes since some tools use
hidden APIs to introspect the screen.public boolean isDestroyed()
public void setOnAccessibilityEventListener(UiAutomation.OnAccessibilityEventListener listener)
AccessibilityEvent
s.listener
- The callback.public void destroy()
public final boolean performGlobalAction(int action)
action
- The action to perform.AccessibilityService.GLOBAL_ACTION_BACK
,
AccessibilityService.GLOBAL_ACTION_HOME
,
AccessibilityService.GLOBAL_ACTION_NOTIFICATIONS
,
AccessibilityService.GLOBAL_ACTION_RECENTS
public AccessibilityNodeInfo findFocus(int focus)
Note: In order to access the windows you have to opt-in
to retrieve the interactive windows by setting the
AccessibilityServiceInfo.FLAG_RETRIEVE_INTERACTIVE_WINDOWS
flag.
Otherwise, the search will be performed only in the active window.
focus
- The focus to find. One of AccessibilityNodeInfo.FOCUS_INPUT
or
AccessibilityNodeInfo.FOCUS_ACCESSIBILITY
.AccessibilityNodeInfo.FOCUS_INPUT
,
AccessibilityNodeInfo.FOCUS_ACCESSIBILITY
public final AccessibilityServiceInfo getServiceInfo()
AccessibilityServiceInfo
describing this UiAutomation.
This method is useful if one wants to change some of the dynamically
configurable properties at runtime.AccessibilityServiceInfo
public final void setServiceInfo(AccessibilityServiceInfo info)
AccessibilityServiceInfo
that describes how this
UiAutomation will be handled by the platform accessibility layer.info
- The info.AccessibilityServiceInfo
public List<AccessibilityWindowInfo> getWindows()
Note: In order to access the windows you have to opt-in
to retrieve the interactive windows by setting the
AccessibilityServiceInfo.FLAG_RETRIEVE_INTERACTIVE_WINDOWS
flag.
public AccessibilityNodeInfo getRootInActiveWindow()
AccessibilityNodeInfo
in the active window.public boolean injectInputEvent(InputEvent event, boolean sync)
Note: It is caller's responsibility to recycle the event.
event
- The event to inject.sync
- Whether to inject the event synchronously.public boolean setRotation(int rotation)
rotation
- The desired rotation.ROTATION_FREEZE_0
,
ROTATION_FREEZE_90
,
ROTATION_FREEZE_180
,
ROTATION_FREEZE_270
,
ROTATION_FREEZE_CURRENT
,
ROTATION_UNFREEZE
public AccessibilityEvent executeAndWaitForEvent(Runnable command, UiAutomation.AccessibilityEventFilter filter, long timeoutMillis) throws TimeoutException
Note: It is caller's responsibility to recycle the returned event.
command
- The command to execute.filter
- Filter that recognizes the expected event.timeoutMillis
- The wait timeout in milliseconds.TimeoutException
- If the expected event is not received within the timeout.public void waitForIdle(long idleTimeoutMillis, long globalTimeoutMillis) throws TimeoutException
idleTimeoutMillis
.
The total time spent to wait for an idle accessibility event stream is bounded
by the globalTimeoutMillis
.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.TimeoutException
- If no idle state was detected within
globalTimeoutMillis.
public Bitmap takeScreenshot()
public void setRunAsMonkey(boolean enable)
enable
- whether to run in a "monkey" mode or not. Default is not.ActivityManager.isUserAMonkey()
public boolean clearWindowContentFrameStats(int windowId)
windowId
- The window id.WindowContentFrameStats
,
getWindowContentFrameStats(int)
,
getWindows()
,
AccessibilityWindowInfo.getId()
public WindowContentFrameStats getWindowContentFrameStats(int windowId)
A typical usage requires clearing the window frame statistics via clearWindowContentFrameStats(int)
followed by an interaction with the UI and
finally getting the window frame statistics via calling this method.
// Assume we have at least one window. final int windowId = getWindows().get(0).getId(); // Start with a clean slate. uiAutimation.clearWindowContentFrameStats(windowId); // Do stuff with the UI. // Get the frame statistics. WindowContentFrameStats stats = uiAutomation.getWindowContentFrameStats(windowId);
windowId
- The window id.WindowContentFrameStats
,
clearWindowContentFrameStats(int)
,
getWindows()
,
AccessibilityWindowInfo.getId()
public void clearWindowAnimationFrameStats()
WindowAnimationFrameStats
,
getWindowAnimationFrameStats()
,
android.R.styleable#WindowAnimation
public WindowAnimationFrameStats getWindowAnimationFrameStats()
A typical usage requires clearing the window animation frame statistics via
clearWindowAnimationFrameStats()
followed by an interaction that causes
a window transition which uses a window animation and finally getting the window
animation frame statistics by calling this method.
// Start with a clean slate. uiAutimation.clearWindowAnimationFrameStats(); // Do stuff to trigger a window transition. // Get the frame statistics. WindowAnimationFrameStats stats = uiAutomation.getWindowAnimationFrameStats();
WindowAnimationFrameStats
,
clearWindowAnimationFrameStats()
,
android.R.styleable#WindowAnimation
public boolean grantRuntimePermission(String packageName, String permission, UserHandle userHandle)
packageName
- The package to which to grant.permission
- The permission to grant.public boolean revokeRuntimePermission(String packageName, String permission, UserHandle userHandle)
packageName
- The package from which to revoke.permission
- The permission to revoke.public ParcelFileDescriptor executeShellCommand(String command)
Note: It is your responsibility to close the retunred file descriptor once you are done reading.
command
- The command to execute.