From 94b3f8eee62f8d2b1076654072d61e67654ed977 Mon Sep 17 00:00:00 2001 From: Quddus Chong Date: Fri, 5 Oct 2012 15:30:20 -0700 Subject: docs: Added new docs for uiautomator testing framework. Change-Id: I9fea9e7a711a37bb1f2492b4aa3938e147614125 --- docs/html/images/testing/UIAutomatorViewer.png | Bin 0 -> 222683 bytes docs/html/tools/help/android.jd | 32 +- .../tools/help/uiautomator/IAutomationSupport.jd | 168 ++ .../tools/help/uiautomator/UiAutomatorTestCase.jd | 1402 +++++++++ docs/html/tools/help/uiautomator/UiCollection.jd | 1271 ++++++++ docs/html/tools/help/uiautomator/UiDevice.jd | 3058 ++++++++++++++++++++ docs/html/tools/help/uiautomator/UiObject.jd | 2684 +++++++++++++++++ .../help/uiautomator/UiObjectNotFoundException.jd | 630 ++++ docs/html/tools/help/uiautomator/UiScrollable.jd | 2914 +++++++++++++++++++ docs/html/tools/help/uiautomator/UiSelector.jd | 2088 +++++++++++++ docs/html/tools/help/uiautomator/UiWatcher.jd | 78 + docs/html/tools/help/uiautomator/index.jd | 177 ++ docs/html/tools/testing/testing_ui.jd | 356 +++ docs/html/tools/tools_toc.cs | 18 + 14 files changed, 14872 insertions(+), 4 deletions(-) create mode 100644 docs/html/images/testing/UIAutomatorViewer.png create mode 100644 docs/html/tools/help/uiautomator/IAutomationSupport.jd create mode 100644 docs/html/tools/help/uiautomator/UiAutomatorTestCase.jd create mode 100644 docs/html/tools/help/uiautomator/UiCollection.jd create mode 100644 docs/html/tools/help/uiautomator/UiDevice.jd create mode 100644 docs/html/tools/help/uiautomator/UiObject.jd create mode 100644 docs/html/tools/help/uiautomator/UiObjectNotFoundException.jd create mode 100644 docs/html/tools/help/uiautomator/UiScrollable.jd create mode 100644 docs/html/tools/help/uiautomator/UiSelector.jd create mode 100644 docs/html/tools/help/uiautomator/UiWatcher.jd create mode 100644 docs/html/tools/help/uiautomator/index.jd create mode 100644 docs/html/tools/testing/testing_ui.jd diff --git a/docs/html/images/testing/UIAutomatorViewer.png b/docs/html/images/testing/UIAutomatorViewer.png new file mode 100644 index 0000000..5a4aaa4 Binary files /dev/null and b/docs/html/images/testing/UIAutomatorViewer.png differ diff --git a/docs/html/tools/help/android.jd b/docs/html/tools/help/android.jd index 282c791..19891e8 100644 --- a/docs/html/tools/help/android.jd +++ b/docs/html/tools/help/android.jd @@ -280,7 +280,7 @@ and may be out of date. For the most current list of options, execute andr - create-test-project + create test-project -n <name> @@ -306,7 +306,7 @@ and may be out of date. For the most current list of options, execute andr - update-test-project + update test-project -p <path> @@ -324,7 +324,7 @@ and may be out of date. For the most current list of options, execute andr - create-lib-project + create lib-project -k <packageName> @@ -358,7 +358,7 @@ and may be out of date. For the most current list of options, execute andr - update-lib-project + update lib-project -p <path> @@ -382,6 +382,30 @@ and may be out of date. For the most current list of options, execute andr + + + create uitest-project + -n <name> + The name of the UI test project + + + + + -t <name> + + Target ID of the UI test project + + Required + + + + -p <path> + + Location path of the UI test project + + Required + +

Update actions

diff --git a/docs/html/tools/help/uiautomator/IAutomationSupport.jd b/docs/html/tools/help/uiautomator/IAutomationSupport.jd new file mode 100644 index 0000000..4120f2b --- /dev/null +++ b/docs/html/tools/help/uiautomator/IAutomationSupport.jd @@ -0,0 +1,168 @@ +page.title=IAutomationSupport +parent.title=uiautomator +parent.link=index.html +@jd:body + + +

Class Overview

+

Provides auxiliary support for running test cases + +

+ + + + + + + + + + + + + + + + + + + + + + +
+ + +

Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Public Methods
+ abstract + + + + + void + + sendStatus(int resultCode, Bundle status) + +
Allows the running test cases to send out interim status
+ +
+ + + + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Public Methods

+ + + + + +
+

+ + public + + + abstract + + void + + sendStatus + (int resultCode, Bundle status) +

+
+
+ +
+ + + +
+
+ +

Allows the running test cases to send out interim status

+ +
+
+ + + diff --git a/docs/html/tools/help/uiautomator/UiAutomatorTestCase.jd b/docs/html/tools/help/uiautomator/UiAutomatorTestCase.jd new file mode 100644 index 0000000..48c63ba --- /dev/null +++ b/docs/html/tools/help/uiautomator/UiAutomatorTestCase.jd @@ -0,0 +1,1402 @@ +page.title=UiAutomatorTestCase +parent.title=uiautomator +parent.link=index.html +@jd:body + +

Class Overview

+

UI automation tests should extend this class. This class provides access + to the following: +

    +
  • UiDevice instance
    • +
  • Bundle for command line parameters
    • +
+

+ + + + + + + + + + + + + + + + + + + + + + +
+ + +

Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Public Constructors
+ + + + + + + + UiAutomatorTestCase() + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Public Methods
+ + + + + + IAutomationSupport + + getAutomationSupport() + +
Provides support for running tests to report interim status
+ +
+ + + + + + Bundle + + getParams() + +
Get command line parameters.
+ +
+ + + + + + UiDevice + + getUiDevice() + +
Get current instance of UiDevice.
+ +
+ + + + + + void + + sleep(long ms) + +
Calls sleep(long) to sleep
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ [Expand] +
Inherited Methods
+ +From class + + junit.framework.TestCase + +
+ + +
+
+ +From class + + junit.framework.Assert + +
+ + +
+
+ +From class + + java.lang.Object + +
+ + +
+
+ +From interface + + junit.framework.Test + +
+ + +
+
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +

Public Constructors

+ + + + + +
+

+ + public + + + + + + + UiAutomatorTestCase + () +

+
+
+ +
+ + + +
+
+ +

+ +
+
+ + + + + + + + + + + + + +

Public Methods

+ + + + + +
+

+ + public + + + + + IAutomationSupport + + getAutomationSupport + () +

+
+
+ +
+ + + +
+
+ +

Provides support for running tests to report interim status

+ +
+
+ + + + +
+

+ + public + + + + + Bundle + + getParams + () +

+
+
+ +
+ + + +
+
+ +

Get command line parameters. On the command line when passing -e key value + pairs, the Bundle will have the key value pairs conveniently available to the + tests. +

+ +
+
+ + + + +
+

+ + public + + + + + UiDevice + + getUiDevice + () +

+
+
+ +
+ + + +
+
+ +

Get current instance of UiDevice. Works similar to calling the static + getInstance() from anywhere in the test classes. +

+ +
+
+ + + + +
+

+ + public + + + + + void + + sleep + (long ms) +

+
+
+ +
+ + + +
+
+ +

Calls sleep(long) to sleep

+
+
Parameters
+ + + + + +
msis in milliseconds. +
+
+ +
+
+ diff --git a/docs/html/tools/help/uiautomator/UiCollection.jd b/docs/html/tools/help/uiautomator/UiCollection.jd new file mode 100644 index 0000000..ed92ca7 --- /dev/null +++ b/docs/html/tools/help/uiautomator/UiCollection.jd @@ -0,0 +1,1271 @@ +page.title=UiCollection +parent.title=uiautomator +parent.link=index.html +@jd:body + +

Used to enumerate a container's user interface (UI) elements for the purpose of counting, + or targeting a sub elements by a child's text or description. +

+ +
+ + +

Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Public Constructors
+ + + + + + + + UiCollection(UiSelector selector) + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Public Methods
+ + + + + + UiObject + + getChildByDescription(UiSelector childPattern, String text) + +
Searches for child UI element within the constraints of this UiSelector + selector.
+ +
+ + + + + + UiObject + + getChildByInstance(UiSelector childPattern, int instance) + +
Searches for child UI element within the constraints of this UiSelector.
+ +
+ + + + + + UiObject + + getChildByText(UiSelector childPattern, String text) + +
Searches for child UI element within the constraints of this UiSelector.
+ +
+ + + + + + int + + getChildCount(UiSelector childPattern) + +
Counts child UI element instances matching the childPattern + argument.
+ +
+ + + + + + + + + + + + + + + + + + + + +
+ [Expand] +
Inherited Methods
+ +From class + + com.android.uiautomator.core.UiObject + +
+ + +
+
+ +From class + + java.lang.Object + +
+ + +
+
+ + +
+ + + +

Public Constructors

+ + + + +
+

+ + public + + + + + + + UiCollection + (UiSelector selector) +

+
+
+ +
+ + + +
+
+ +

+ +
+
+ + + + + + +

Public Methods

+ + + + +
+

+ + public + + + + + UiObject + + getChildByDescription + (UiSelector childPattern, String text) +

+
+
+ +
+ + + +
+
+ +

Searches for child UI element within the constraints of this UiSelector + selector. + + It looks for any child matching the childPattern argument that has + a child UI element anywhere within its sub hierarchy that has content-description text. + The returned UiObject will point at the childPattern instance that matched the + search and not at the identifying child element that matched the content description.

+
+
Parameters
+ + + + + + + + + +
childPatternUiSelector selector of the child pattern to match and return
textString of the identifying child contents of of the childPattern
+
+
+
Returns
+
  • UiObject pointing at and instance of childPattern
+
+
+
Throws
+ + + + +
UiObjectNotFoundException +
+
+ +
+
+ + + + +
+

+ + public + + + + + UiObject + + getChildByInstance + (UiSelector childPattern, int instance) +

+
+
+ +
+ + + +
+
+ +

Searches for child UI element within the constraints of this UiSelector. + + It looks for any child matching the childPattern argument that has + a child UI element anywhere within its sub hierarchy that is at the instance + specified. The operation is performed only on the visible items and no scrolling is performed + in this case.

+
+
Parameters
+ + + + + + + + + +
childPatternUiSelector selector of the child pattern to match and return
instanceint the desired matched instance of this childPattern
+
+
+
Returns
+
  • UiObject pointing at and instance of childPattern +
+
+
+
Throws
+ + + + +
UiObjectNotFoundException +
+
+ +
+
+ + + + +
+

+ + public + + + + + UiObject + + getChildByText + (UiSelector childPattern, String text) +

+
+
+ +
+ + + +
+
+ +

Searches for child UI element within the constraints of this UiSelector + selector. + + It looks for any child matching the childPattern argument that has + a child UI element anywhere within its sub hierarchy that has a text attribute equal to + text. The returned UiObject will point at the childPattern + instance that matched the search and not at the identifying child element that matched the + text attribute.

+
+
Parameters
+ + + + + + + + + +
childPatternUiSelector selector of the child pattern to match and return
textString of the identifying child contents of of the childPattern
+
+
+
Returns
+
  • UiObject pointing at and instance of childPattern
+
+
+
Throws
+ + + + +
UiObjectNotFoundException +
+
+ +
+
+ + + + +
+

+ + public + int + + getChildCount + (UiSelector childPattern) +

+
+
+
+ +

Counts child UI element instances matching the childPattern + argument. The method returns the number of matching UI elements that are + currently visible. The count does not include items of a scrollable list + that are off-screen.

+
+
Parameters
+ + + + + +
childPatterna UiSelector that represents the matching child UI + elements to count
+
+
+
Returns
+
  • the number of matched childPattern under the current UiCollection +
+
+ +
+
+ diff --git a/docs/html/tools/help/uiautomator/UiDevice.jd b/docs/html/tools/help/uiautomator/UiDevice.jd new file mode 100644 index 0000000..0c0c7d9 --- /dev/null +++ b/docs/html/tools/help/uiautomator/UiDevice.jd @@ -0,0 +1,3058 @@ +page.title=UiDevice +parent.title=uiautomator +parent.link=index.html +@jd:body + + +

Class Overview

+

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
+ +
+ + + + + + 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@return
+ +
+ + + + + + 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 + + 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) + +
Simulates a short press using a key code.
+ +
+ + + + + + boolean + + pressKeyCode(int keyCode, int metaState) + +
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 + + 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, float scale, int quality) + +
Take a screenshot of current window and store it as PNG + + The screenshot is adjusted per screen rotation
+ +
+ + + + + + 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
+ +
+ + + + + + 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 time) + +
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
+ + + + + + + + + +
xcoordinate
ycoordinate
+
+
+
Returns
+
  • true if the click succeeded else false
+
+ +
+
+ + + + +
+

+ + 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@return

+
+
Since
+
  • Android API Level 17
+
+
+
+ + + + +
+

+ + 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
+
+ +
+
+ + + + +
+

+ + 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
+
+ +
+
+ + + + +
+

+ + 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 + + 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) +

+
+
+ +
+ + + +
+
+ +

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

+
+
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
+ + + + + + + + + +
keyCodethe key code of the event.
metaStatean integer in which each bit set to 1 represents a pressed meta key
+
+
+
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
+ + + + + + + + + +
nameto register the UiWatcher
watcherUiWatcher
+
+ +
+
+ + + + +
+

+ + public + + + + + void + + removeWatcher + (String name) +

+
+
+ +
+ + + +
+
+ +

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

+
+
Parameters
+ + + + + +
nameused to register the UiWatcher
+
+
+
Throws
+ + + + +
+ UiAutomationException
+
+ +
+
+ + + + +
+

+ + 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 + + 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 +
+
+ +
+
+ + + + +
+

+ + 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 +
+
+ +
+
+ + + + +
+

+ + 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 +
+
+ +
+
+ + + + +
+

+ + 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
+ + + + + + + + + +
segmentsis Point array containing at least one Point object
segmentStepssteps 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
+ + + + + +
stepsis 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, float scale, int quality) +

+
+
+ +
+ + + +
+
+ +

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

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

+ + 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
+ + + + + +
storePathwhere the PNG should be written to
+
+
+
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 time) +

+
+
+ +
+ + + +
+
+ +

Waits for the current application to idle.

+ +
+
+ + + + +
+

+ + 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
+ + + + + + + + + +
packageNamethe specified window package name (can be null). + If null, a window update from any front-end window will end the wait
timeoutthe 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 +
+
+ +
+
+ + + + + + + + + + + diff --git a/docs/html/tools/help/uiautomator/UiObject.jd b/docs/html/tools/help/uiautomator/UiObject.jd new file mode 100644 index 0000000..799ac82 --- /dev/null +++ b/docs/html/tools/help/uiautomator/UiObject.jd @@ -0,0 +1,2684 @@ +page.title=UiObject +parent.title=uiautomator +parent.link=index.html +@jd:body + +

A UiObject is a representation of a user interface (UI) element. It is not in any way directly bound to a + UI element as an object reference. A UiObject holds information to help it + locate a matching UI element at runtime based on the UiSelector properties specified in + its constructor. Since a UiObject is a representative for a UI element, it can + be reused for different views with matching UI elements. +

+ + + + + + + + + + + + + + + + + +
+ + +

Summary

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Public Constructors
+ + + + + + + + UiObject(UiSelector selector) + +
Constructs a UiObject to represent a specific UI element matched by the specified + UiSelector selector properties.
+ +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Public Methods
+ + + + + + void + + clearTextField() + +
Clears the existing text contents in an editable field.
+ +
+ + + + + + boolean + + click() + +
Performs a click at the center of the visible bounds of the UI element represented + by this UiObject.
+ +
+ + + + + + boolean + + clickAndWaitForNewWindow(long timeout) + +
Performs a click at the center of the visible bounds of the UI element represented + by this UiObject and waits for window transitions.
+ +
+ + + + + + boolean + + clickAndWaitForNewWindow() + +
See clickAndWaitForNewWindow(long) + This method is intended to reliably wait for window transitions that would typically take + longer than the usual default timeouts.
+ +
+ + + + + + boolean + + clickBottomRight() + +
Clicks the bottom and right corner of the UI element
+ +
+ + + + + + boolean + + clickTopLeft() + +
Clicks the top and left corner of the UI element
+ +
+ + + + + + boolean + + exists() + +
Check if UI element exists.
+ +
+ + + + + + Rect + + getBounds() + +
Returns the UI element's bounds property.
+ +
+ + + + + + UiObject + + getChild(UiSelector selector) + +
Creates a new UiObject representing a child UI element of the element currently represented + by this UiObject.
+ +
+ + + + + + int + + getChildCount() + +
Counts the child UI elements immediately under the UI element currently represented by + this UiObject.
+ +
+ + + + + + String + + getContentDescription() + +
Reads the content_desc property of the UI element
+ +
+ + + + + + UiObject + + getFromParent(UiSelector selector) + +
Creates a new UiObject representing a child UI element from the parent element currently + represented by this object.
+ +
+ + + + + + String + + getPackageName() + +
Reads the UI element's package property
+ +
+ + + final + + + UiSelector + + getSelector() + +
Debugging helper.
+ +
+ + + + + + String + + getText() + +
Reads the text property of the UI element
+ +
+ + + + + + Rect + + getVisibleBounds() + +
Returns the visible bounds of the UI element.
+ +
+ + + + + + boolean + + isCheckable() + +
Check if the UI element's checkable property is currently true
+ +
+ + + + + + boolean + + isChecked() + +
Check if the UI element's checked property is currently true
+ +
+ + + + + + boolean + + isClickable() + +
Check if the UI element's clickable property is currently true
+ +
+ + + + + + boolean + + isEnabled() + +
Check if the UI element's enabled property is currently true
+ +
+ + + + + + boolean + + isFocusable() + +
Check if the UI element's focusable property is currently true
+ +
+ + + + + + boolean + + isFocused() + +
Check if the UI element's focused property is currently true
+ +
+ + + + + + boolean + + isLongClickable() + +
Check if the UI element's long-clickable property is currently true
+ +
+ + + + + + boolean + + isScrollable() + +
Check if the UI element's scrollable property is currently true
+ +
+ + + + + + boolean + + isSelected() + +
Check if the UI element's selected property is currently true
+ +
+ + + + + + boolean + + longClick() + +
Long clicks the center of the visible bounds of the UI element
+ +
+ + + + + + boolean + + longClickBottomRight() + +
Long clicks bottom and right corner of the UI element
+ +
+ + + + + + boolean + + longClickTopLeft() + +
Long clicks on the top and left corner of the UI element
+ +
+ + + + + + boolean + + setText(String text) + +
Sets the text in an editable field, after clearing the field's content.
+ +
+ + + + + + boolean + + swipeDown(int steps) + +
Perform the action on the UI element that is represented by this object, Also see + #scrollToBeginning(int), #scrollToEnd(int), #scrollBackward(), + #scrollForward().
+ +
+ + + + + + boolean + + swipeLeft(int steps) + +
Perform the action on the UI element that is represented by this object.
+ +
+ + + + + + boolean + + swipeRight(int steps) + +
Perform the action on the UI element that is represented by this object.
+ +
+ + + + + + boolean + + swipeUp(int steps) + +
Perform the action on the UI element that is represented by this UiObject.
+ +
+ + + + + + boolean + + waitForExists(long timeout) + +
Waits a specified length of time for a UI element to become visible.
+ +
+ + + + + + boolean + + waitUntilGone(long timeout) + +
Waits a specified length of time for a UI element to become undetectable.
+ +
+ + + + + + + + + + + + + + + +
+ [Expand] +
Inherited Methods
+ +From class + + java.lang.Object + +
+ + +
+
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + +

Public Constructors

+ + + + + +
+

+ + public + + + + + + + UiObject + (UiSelector selector) +

+
+
+ +
+ + + +
+
+ +

Constructs a UiObject to represent a specific UI element matched by the specified + UiSelector selector properties.

+ +
+
+ + + + + + + + + + + + + +

Public Methods

+ + + + + +
+

+ + public + + + + + void + + clearTextField + () +

+
+
+ +
+ + + +
+
+ +

Clears the existing text contents in an editable field. + + The UiSelector of this object must reference a UI element that is editable. + + When you call this method, the method first sets focus at the start edge of the field. + The method then simulates a long-press to select the existing text, and deletes the + selected text. + + If a "Select-All" option is displayed, the method will automatically attempt to use it + to ensure full text selection. + + Note that it is possible that not all the text in the field is selected; for example, + if the text contains separators such as spaces, slashes, at symbol etc. + Also, not all editable fields support the long-press functionality.

+
+
Throws
+ + + + +
UiObjectNotFoundException +
+
+ +
+
+ + + + +
+

+ + public + + + + + boolean + + click + () +

+
+
+ +
+ + + +
+
+ +

Performs a click at the center of the visible bounds of the UI element represented + by this UiObject.

+
+
Returns
+
  • true id successful else false
+
+
+
Throws
+ + + + +
UiObjectNotFoundException +
+
+ +
+
+ + + + +
+

+ + public + + + + + boolean + + clickAndWaitForNewWindow + (long timeout) +

+
+
+ +
+ + + +
+
+ +

Performs a click at the center of the visible bounds of the UI element represented + by this UiObject and waits for window transitions. + + This method differ from click() only in that this method waits for a + a new window transition as a result of the click. Some examples of a window transition: +

  • launching a new activity
    • +
  • bringing up a pop-up menu
    • +
  • bringing up a dialog

    • +
    +
    Parameters
    + + + + + +
    timeouttimeout before giving up on waiting for a new window
    +
    +
    +
    Returns
    +
    • true if the event was triggered, else false
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + clickAndWaitForNewWindow + () +

    +
    +
    + +
    + + + +
    +
    + +

    See clickAndWaitForNewWindow(long) + This method is intended to reliably wait for window transitions that would typically take + longer than the usual default timeouts.

    +
    +
    Returns
    +
    • true if the event was triggered, else false
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + clickBottomRight + () +

    +
    +
    + +
    + + + +
    +
    + +

    Clicks the bottom and right corner of the UI element

    +
    +
    Returns
    +
    • true on success
    +
    +
    +
    Throws
    + + + + + + + +
    Exception +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + clickTopLeft + () +

    +
    +
    + +
    + + + +
    +
    + +

    Clicks the top and left corner of the UI element

    +
    +
    Returns
    +
    • true on success
    +
    +
    +
    Throws
    + + + + + + + +
    Exception +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + exists + () +

    +
    +
    + +
    + + + +
    +
    + +

    Check if UI element exists. + + This methods performs a waitForExists(long) with zero timeout. This + basically returns immediately whether the UI element represented by this UiObject + exists or not. If you need to wait longer for this UI element, then see + waitForExists(long).

    +
    +
    Returns
    +
    • true if the UI element represented by this UiObject does exist +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + Rect + + getBounds + () +

    +
    +
    + +
    + + + +
    +
    + +

    Returns the UI element's bounds property. See getVisibleBounds()

    +
    +
    Returns
    +
    • Rect
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiObject + + getChild + (UiSelector selector) +

    +
    +
    + +
    + + + +
    +
    + +

    Creates a new UiObject representing a child UI element of the element currently represented + by this UiObject.

    +
    +
    Parameters
    + + + + + +
    selectorfor UI element to match
    +
    +
    +
    Returns
    +
    • a new UiObject representing the matched UI element +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + int + + getChildCount + () +

    +
    +
    + +
    + + + +
    +
    + +

    Counts the child UI elements immediately under the UI element currently represented by + this UiObject.

    +
    +
    Returns
    +
    • the count of child UI elements.
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + String + + getContentDescription + () +

    +
    +
    + +
    + + + +
    +
    + +

    Reads the content_desc property of the UI element

    +
    +
    Returns
    +
    • value of node attribute "content_desc"
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiObject + + getFromParent + (UiSelector selector) +

    +
    +
    + +
    + + + +
    +
    + +

    Creates a new UiObject representing a child UI element from the parent element currently + represented by this object. Essentially this is starting the search from the parent + element and can also be used to find sibling UI elements to the one currently represented + by this UiObject.

    +
    +
    Parameters
    + + + + + +
    selectorfor the UI element to match
    +
    +
    +
    Returns
    +
    • a new UiObject representing the matched UI element
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + String + + getPackageName + () +

    +
    +
    + +
    + + + +
    +
    + +

    Reads the UI element's package property

    +
    +
    Returns
    +
    • true if it is else false
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + final + + + UiSelector + + getSelector + () +

    +
    +
    + +
    + + + +
    +
    + +

    Debugging helper. A test can dump the properties of a selector as a string + to its logs if needed. getSelector().toString();

    +
    +
    Returns
    + +
    + +
    +
    + + + + +
    +

    + + public + + + + + String + + getText + () +

    +
    +
    + +
    + + + +
    +
    + +

    Reads the text property of the UI element

    +
    +
    Returns
    +
    • text value of the current node represented by this UiObject
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException + if no match could be found +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + Rect + + getVisibleBounds + () +

    +
    +
    + +
    + + + +
    +
    + +

    Returns the visible bounds of the UI element. + + If a portion of the UI element is visible, only the bounds of the visible portion are + reported.

    +
    +
    Returns
    +
    • Rect
    +
    +
    +
    Throws
    + + + + + + + +
    + UiObjectNotFoundException
    UiObjectNotFoundException +
    +
    +
    +
    + + + + +
    +

    + + public + + + + + boolean + + isCheckable + () +

    +
    +
    + +
    + + + +
    +
    + +

    Check if the UI element's checkable property is currently true

    +
    +
    Returns
    +
    • true if it is else false
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + isChecked + () +

    +
    +
    + +
    + + + +
    +
    + +

    Check if the UI element's checked property is currently true

    +
    +
    Returns
    +
    • true if it is else false +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + isClickable + () +

    +
    +
    + +
    + + + +
    +
    + +

    Check if the UI element's clickable property is currently true

    +
    +
    Returns
    +
    • true if it is else false
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + isEnabled + () +

    +
    +
    + +
    + + + +
    +
    + +

    Check if the UI element's enabled property is currently true

    +
    +
    Returns
    +
    • true if it is else false
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + isFocusable + () +

    +
    +
    + +
    + + + +
    +
    + +

    Check if the UI element's focusable property is currently true

    +
    +
    Returns
    +
    • true if it is else false
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + isFocused + () +

    +
    +
    + +
    + + + +
    +
    + +

    Check if the UI element's focused property is currently true

    +
    +
    Returns
    +
    • true if it is else false
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + isLongClickable + () +

    +
    +
    + +
    + + + +
    +
    + +

    Check if the UI element's long-clickable property is currently true

    +
    +
    Returns
    +
    • true if it is else false
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + isScrollable + () +

    +
    +
    + +
    + + + +
    +
    + +

    Check if the UI element's scrollable property is currently true

    +
    +
    Returns
    +
    • true if it is else false
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + isSelected + () +

    +
    +
    + +
    + + + +
    +
    + +

    Check if the UI element's selected property is currently true

    +
    +
    Returns
    +
    • true if it is else false
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + longClick + () +

    +
    +
    + +
    + + + +
    +
    + +

    Long clicks the center of the visible bounds of the UI element

    +
    +
    Returns
    +
    • true if operation was successful
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + longClickBottomRight + () +

    +
    +
    + +
    + + + +
    +
    + +

    Long clicks bottom and right corner of the UI element

    +
    +
    Returns
    +
    • true if operation was successful
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + longClickTopLeft + () +

    +
    +
    + +
    + + + +
    +
    + +

    Long clicks on the top and left corner of the UI element

    +
    +
    Returns
    +
    • true if operation was successful
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + setText + (String text) +

    +
    +
    + +
    + + + +
    +
    + +

    Sets the text in an editable field, after clearing the field's content. + + The UiSelector selector of this object must reference a UI element that is editable. + + When you call this method, the method first simulates a click() on + editable field to set focus. The method then clears the field's contents + and injects your specified text into the field. + + If you want to capture the original contents of the field, call getText() first. + You can then modify the text and use this method to update the field.

    +
    +
    Parameters
    + + + + + +
    textstring to set
    +
    +
    +
    Returns
    +
    • true if operation is successful
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + swipeDown + (int steps) +

    +
    +
    + +
    + + + +
    +
    + +

    Perform the action on the UI element that is represented by this object, Also see + #scrollToBeginning(int), #scrollToEnd(int), #scrollBackward(), + #scrollForward(). This method will perform the swipe gesture over any + surface. The targeted UI element does not need to have the attribute + scrollable set to true for this operation to be performed.

    +
    +
    Parameters
    + + + + + +
    stepsindicates the number of injected move steps into the system. Steps are + injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.
    +
    +
    +
    Returns
    +
    • true if successful
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + swipeLeft + (int steps) +

    +
    +
    + +
    + + + +
    +
    + +

    Perform the action on the UI element that is represented by this object. Also see + #scrollToBeginning(int), #scrollToEnd(int), #scrollBackward(), + #scrollForward(). This method will perform the swipe gesture over any + surface. The targeted UI element does not need to have the attribute + scrollable set to true for this operation to be performed.

    +
    +
    Parameters
    + + + + + +
    stepsindicates the number of injected move steps into the system. Steps are + injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.
    +
    +
    +
    Returns
    +
    • true if successful
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + swipeRight + (int steps) +

    +
    +
    + +
    + + + +
    +
    + +

    Perform the action on the UI element that is represented by this object. Also see + #scrollToBeginning(int), #scrollToEnd(int), #scrollBackward(), + #scrollForward(). This method will perform the swipe gesture over any + surface. The targeted UI element does not need to have the attribute + scrollable set to true for this operation to be performed.

    +
    +
    Parameters
    + + + + + +
    stepsindicates the number of injected move steps into the system. Steps are + injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.
    +
    +
    +
    Returns
    +
    • true if successful
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + swipeUp + (int steps) +

    +
    +
    + +
    + + + +
    +
    + +

    Perform the action on the UI element that is represented by this UiObject. Also see + #scrollToBeginning(int), #scrollToEnd(int), #scrollBackward(), + #scrollForward().

    +
    +
    Parameters
    + + + + + +
    stepsindicates the number of injected move steps into the system. Steps are + injected about 5ms apart. So a 100 steps may take about 1/2 second to complete.
    +
    +
    +
    Returns
    +
    • true of successful
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + waitForExists + (long timeout) +

    +
    +
    + +
    + + + +
    +
    + +

    Waits a specified length of time for a UI element to become visible. + + This method waits until the UI element becomes visible on the display, or + until the timeout has elapsed. You can use this method in situations where + the content that you want to select is not immediately displayed.

    +
    +
    Parameters
    + + + + + +
    timeoutthe amount of time to wait (in milliseconds)
    +
    +
    +
    Returns
    +
    • true if the UI element is displayed, else false if timeout elapsed while waiting +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + waitUntilGone + (long timeout) +

    +
    +
    + +
    + + + +
    +
    + +

    Waits a specified length of time for a UI element to become undetectable. + + This method waits until a UI element is no longer matchable, or until the + timeout has elapsed. + + A UI element becomes undetectable when the UiSelector of the object is + unable to find a match because the element has either changed its state or is no + longer displayed. + + You can use this method when attempting to wait for some long operation + to compete, such as downloading a large file or connecting to a remote server.

    +
    +
    Parameters
    + + + + + +
    timeouttime to wait (in milliseconds)
    +
    +
    +
    Returns
    +
    • true if the element is gone before timeout elapsed, else false if timeout elapsed + but a matching element is still found. +
    +
    + +
    +
    + diff --git a/docs/html/tools/help/uiautomator/UiObjectNotFoundException.jd b/docs/html/tools/help/uiautomator/UiObjectNotFoundException.jd new file mode 100644 index 0000000..02c607d --- /dev/null +++ b/docs/html/tools/help/uiautomator/UiObjectNotFoundException.jd @@ -0,0 +1,630 @@ +page.title=UiObjectNotFoundException +parent.title=uiautomator +parent.link=index.html +@jd:body + +

    Generated in test runs when a UiSelector selector could not be matched + to any UI element displayed. +

    + + + + + + + + + + + + + + + + + + + + + +
    + + +

    Summary

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Public Constructors
    + + + + + + + + UiObjectNotFoundException(String msg) + +
    + + + + + + + + UiObjectNotFoundException(String detailMessage, Throwable throwable) + +
    + + + + + + + + UiObjectNotFoundException(Throwable throwable) + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + [Expand] +
    Inherited Methods
    + +From class + + java.lang.Throwable + +
    + + +
    +
    + +From class + + java.lang.Object + +
    + + +
    +
    + + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + +

    Public Constructors

    + + + + + +
    +

    + + public + + + + + + + UiObjectNotFoundException + (String msg) +

    +
    +
    + +
    + + + +
    +
    + +

    + +
    +
    + + + + +
    +

    + + public + + + + + + + UiObjectNotFoundException + (String detailMessage, Throwable throwable) +

    +
    +
    + +
    + + + +
    +
    + +

    + +
    +
    + + + + +
    +

    + + public + + + + + + + UiObjectNotFoundException + (Throwable throwable) +

    +
    +
    + +
    + + + +
    +
    + +

    + +
    +
    diff --git a/docs/html/tools/help/uiautomator/UiScrollable.jd b/docs/html/tools/help/uiautomator/UiScrollable.jd new file mode 100644 index 0000000..33566a2 --- /dev/null +++ b/docs/html/tools/help/uiautomator/UiScrollable.jd @@ -0,0 +1,2914 @@ +page.title=UiScrollable +parent.title=uiautomator +parent.link=index.html +@jd:body + +

    UiScrollable is a UiCollection and provides support for searching for items in a + scrollable user interface (UI) elements. This class can be used with horizontally or vertically scrollable controls.. +

    + + + + + + + + + + + + + + + + + + + + + +
    + + +

    Summary

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Public Constructors
    + + + + + + + + UiScrollable(UiSelector container) + +
    UiScrollable is a UiCollection and as such requires a UiSelector to + identify the container UI element of the scrollable collection.
    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Public Methods
    + + + + + + boolean + + flingBackward() + +
    See scrollBackward(int)
    + +
    + + + + + + boolean + + flingForward() + +
    A convenience version of scrollForward(int), performs a fling
    + +
    + + + + + + boolean + + flingToBeginning(int maxSwipes) + +
    See scrollToBeginning(int, int)
    + +
    + + + + + + boolean + + flingToEnd(int maxSwipes) + +
    See scrollToEnd(int, int)
    + +
    + + + + + + UiObject + + getChildByDescription(UiSelector childPattern, String text, boolean allowScrollSearch) + +
    See getChildByDescription(UiSelector, String)
    + +
    + + + + + + UiObject + + getChildByDescription(UiSelector childPattern, String text) + +
    Searches for child UI element within the constraints of this UiScrollable UiSelector + container.
    + +
    + + + + + + UiObject + + getChildByInstance(UiSelector childPattern, int instance) + +
    Searches for child UI element within the constraints of this UiScrollable UiSelector + selector.
    + +
    + + + + + + UiObject + + getChildByText(UiSelector childPattern, String text, boolean allowScrollSearch) + +
    See getChildByText(UiSelector, String)
    + +
    + + + + + + UiObject + + getChildByText(UiSelector childPattern, String text) + +
    Searches for child UI element within the constraints of this UiScrollable UiSelector + container.
    + +
    + + + + + + int + + getMaxSearchSwipes() + +
    #getChildByDescription(String, boolean) and #getChildByText(String, boolean) + use an arguments that specifies if scrolling is allowed while searching for the UI element.
    + +
    + + + + + + double + + getSwipeDeadZonePercentage() + +
    Returns the percentage of a widget's size that's considered as a no touch zone when swiping.
    + +
    + + + + + + boolean + + scrollBackward(int steps) + +
    Perform a scroll backward.
    + +
    + + + + + + boolean + + scrollBackward() + +
    See scrollBackward(int)
    + +
    + + + + + + boolean + + scrollDescriptionIntoView(String text) + +
    Performs a swipe Up on the UI element until the requested content-description + is visible or until swipe attempts have been exhausted.
    + +
    + + + + + + boolean + + scrollForward() + +
    A convenience version of scrollForward(int), performs a regular scroll
    + +
    + + + + + + boolean + + scrollForward(int steps) + +
    Perform a scroll forward.
    + +
    + + + + + + boolean + + scrollIntoView(UiSelector selector) + +
    Perform a scroll search for a UI element matching the UiSelector selector argument.
    + +
    + + + + + + boolean + + scrollTextIntoView(String text) + +
    Performs a swipe up on the UI element until the requested text is visible + or until swipe attempts have been exhausted.
    + +
    + + + + + + boolean + + scrollToBeginning(int maxSwipes) + +
    See scrollToBeginning(int, int)
    + +
    + + + + + + boolean + + scrollToBeginning(int maxSwipes, int steps) + +
    Scrolls to the beginning of a scrollable UI element.
    + +
    + + + + + + boolean + + scrollToEnd(int maxSwipes, int steps) + +
    Scrolls to the end of a scrollable UI element.
    + +
    + + + + + + boolean + + scrollToEnd(int maxSwipes) + +
    See {@link UiScrollable#scrollToEnd(int, int)
    + +
    + + + + + + void + + setAsHorizontalList() + +
    Set the direction of swipes when performing scroll search +
    + +
    + + + + + + void + + setAsVerticalList() + +
    Set the direction of swipes when performing scroll search +
    + +
    + + + + + + void + + setMaxSearchSwipes(int swipes) + +
    #getChildByDescription(String, boolean) and #getChildByText(String, boolean) + use an arguments that specifies if scrolling is allowed while searching for the UI element.
    + +
    + + + + + + void + + setSwipeDeadZonePercentage(double swipeDeadZonePercentage) + +
    Sets the percentage of a widget's size that's considered as a no touch zone when swiping.
    + +
    + + + + + + + + + + + + + + + + + + + + + + + + + +
    + [Expand] +
    Inherited Methods
    + +From class + + com.android.uiautomator.core.UiCollection + +
    + + +
    +
    + +From class + + com.android.uiautomator.core.UiObject + +
    + + +
    +
    + +From class + + java.lang.Object + +
    + + +
    +
    + + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + +

    Public Constructors

    + + + + + +
    +

    + + public + + + + + + + UiScrollable + (UiSelector container) +

    +
    +
    + +
    + + + +
    +
    + +

    UiScrollable is a UiCollection and as such requires a UiSelector to + identify the container UI element of the scrollable collection. Further operations on + the items in the container will require specifying UiSelector as an item selector.

    +
    +
    Parameters
    + + + + + +
    containera UiSelector selector +
    +
    + +
    +
    + + + + + + + + + + + + + +

    Public Methods

    + + + + + +
    +

    + + public + + + + + boolean + + flingBackward + () +

    +
    +
    + +
    + + + +
    +
    + +

    See scrollBackward(int)

    +
    +
    Returns
    +
    • true if scrolled and false if the control can't scroll anymore +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + flingForward + () +

    +
    +
    + +
    + + + +
    +
    + +

    A convenience version of scrollForward(int), performs a fling

    +
    +
    Returns
    +
    • true if scrolled and false if the control can't scroll anymore +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + flingToBeginning + (int maxSwipes) +

    +
    +
    + +
    + + + +
    +
    + +

    See scrollToBeginning(int, int)

    +
    +
    Returns
    +
    • true on scrolled else false +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + flingToEnd + (int maxSwipes) +

    +
    +
    + +
    + + + +
    +
    + +

    See scrollToEnd(int, int)

    +
    +
    Returns
    +
    • true on scrolled else false +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiObject + + getChildByDescription + (UiSelector childPattern, String text, boolean allowScrollSearch) +

    +
    +
    + +
    + + + +
    +
    + +

    See getChildByDescription(UiSelector, String)

    +
    +
    Parameters
    + + + + + + + + + + + + + +
    childPatternUiSelector selector of the child pattern to match and return
    textString may be a partial match for the content-description of a child element.
    allowScrollSearchset to true if scrolling is allowed
    +
    +
    +
    Returns
    +
    • UiObject pointing at and instance of childPattern
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiObject + + getChildByDescription + (UiSelector childPattern, String text) +

    +
    +
    + +
    + + + +
    +
    + +

    Searches for child UI element within the constraints of this UiScrollable UiSelector + container. It looks for any child matching the childPattern argument within its + hierarchy with a matching content-description text. The returned UiObject will represent the + UI element matching the childPattern and not the sub element that matched the + content description.

    + By default this operation will perform scroll search while attempting to find the UI element + See getChildByDescription(UiSelector, String, boolean)

    +
    +
    Parameters
    + + + + + + + + + +
    childPatternUiSelector selector of the child pattern to match and return
    textString of the identifying child contents of of the childPattern
    +
    +
    +
    Returns
    +
    • UiObject pointing at and instance of childPattern
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiObject + + getChildByInstance + (UiSelector childPattern, int instance) +

    +
    +
    + +
    + + + +
    +
    + +

    Searches for child UI element within the constraints of this UiScrollable UiSelector + selector. It looks for any child matching the childPattern argument and + return the instance specified. The operation is performed only on the visible + items and no scrolling is performed in this case.

    +
    +
    Parameters
    + + + + + + + + + +
    childPatternUiSelector selector of the child pattern to match and return
    instanceint the desired matched instance of this childPattern
    +
    +
    +
    Returns
    +
    • UiObject pointing at and instance of childPattern +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiObject + + getChildByText + (UiSelector childPattern, String text, boolean allowScrollSearch) +

    +
    +
    + +
    + + + +
    +
    + +

    See getChildByText(UiSelector, String)

    +
    +
    Parameters
    + + + + + + + + + + + + + +
    childPatternUiSelector selector of the child pattern to match and return
    textString of the identifying child contents of of the childPattern
    allowScrollSearchset to true if scrolling is allowed
    +
    +
    +
    Returns
    +
    • UiObject pointing at and instance of childPattern
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiObject + + getChildByText + (UiSelector childPattern, String text) +

    +
    +
    + +
    + + + +
    +
    + +

    Searches for child UI element within the constraints of this UiScrollable UiSelector + container. It looks for any child matching the childPattern argument that has + a sub UI element anywhere within its sub hierarchy that has text attribute + text. The returned UiObject will point at the childPattern + instance that matched the search and not at the text matched sub element

    + By default this operation will perform scroll search while attempting to find the UI + element. + See getChildByText(UiSelector, String, boolean)

    +
    +
    Parameters
    + + + + + + + + + +
    childPatternUiSelector selector of the child pattern to match and return
    textString of the identifying child contents of of the childPattern
    +
    +
    +
    Returns
    +
    • UiObject pointing at and instance of childPattern
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + int + + getMaxSearchSwipes + () +

    +
    +
    + +
    + + + +
    +
    + +

    #getChildByDescription(String, boolean) and #getChildByText(String, boolean) + use an arguments that specifies if scrolling is allowed while searching for the UI element. + The number of scrolls currently allowed to perform a search can be read by this method. + See setMaxSearchSwipes(int)

    +
    +
    Returns
    +
    • max value of the number of swipes currently allowed during a scroll search +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + double + + getSwipeDeadZonePercentage + () +

    +
    +
    + +
    + + + +
    +
    + +

    Returns the percentage of a widget's size that's considered as a no touch zone when swiping. + + Dead zones are set as percentage of a widget's total width or height, denoting a margin + around the swipable area of the widget. Swipes must start and + end inside this margin. + + This is important when the widget being swiped may not respond to the swipe if + started at a point too near to the edge. The default is 10% from either edge.

    +
    +
    Returns
    +
    • a value between 0 and 1 +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + scrollBackward + (int steps) +

    +
    +
    + +
    + + + +
    +
    + +

    Perform a scroll backward. If this list is set to vertical (see setAsVerticalList() + default) then the swipes will be executed from the top to bottom. If this list is set + to horizontal (see setAsHorizontalList()) then the swipes will be executed from + the left to right. Caution is required on devices configured with right to left languages + like Arabic and Hebrew.

    +
    +
    Parameters
    + + + + + +
    stepsuse steps to control the speed, so that it may be a scroll, or fling
    +
    +
    +
    Returns
    +
    • true if scrolled and false if the control can't scroll anymore +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + scrollBackward + () +

    +
    +
    + +
    + + + +
    +
    + +

    See scrollBackward(int)

    +
    +
    Returns
    +
    • true if scrolled and false if the control can't scroll anymore +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + scrollDescriptionIntoView + (String text) +

    +
    +
    + +
    + + + +
    +
    + +

    Performs a swipe Up on the UI element until the requested content-description + is visible or until swipe attempts have been exhausted. See setMaxSearchSwipes(int)

    +
    +
    Parameters
    + + + + + +
    textto look for anywhere within the contents of this scrollable.
    +
    +
    +
    Returns
    +
    • true if item us found else false +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + scrollForward + () +

    +
    +
    + +
    + + + +
    +
    + +

    A convenience version of scrollForward(int), performs a regular scroll

    +
    +
    Returns
    +
    • true if scrolled and false if the control can't scroll anymore +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + scrollForward + (int steps) +

    +
    +
    + +
    + + + +
    +
    + +

    Perform a scroll forward. If this list is set to vertical (see setAsVerticalList() + default) then the swipes will be executed from the bottom to top. If this list is set + to horizontal (see setAsHorizontalList()) then the swipes will be executed from + the right to left. Caution is required on devices configured with right to left languages + like Arabic and Hebrew.

    +
    +
    Parameters
    + + + + + +
    stepsuse steps to control the speed, so that it may be a scroll, or fling
    +
    +
    +
    Returns
    +
    • true if scrolled and false if the control can't scroll anymore +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + scrollIntoView + (UiSelector selector) +

    +
    +
    + +
    + + + +
    +
    + +

    Perform a scroll search for a UI element matching the UiSelector selector argument. + See scrollDescriptionIntoView(String) and scrollTextIntoView(String).

    +
    +
    Parameters
    + + + + + +
    selectorUiSelector selector
    +
    +
    +
    Returns
    +
    • true if the item was found and now is in view else false +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + scrollTextIntoView + (String text) +

    +
    +
    + +
    + + + +
    +
    + +

    Performs a swipe up on the UI element until the requested text is visible + or until swipe attempts have been exhausted. See setMaxSearchSwipes(int)

    +
    +
    Parameters
    + + + + + +
    textto look for
    +
    +
    +
    Returns
    +
    • true if item us found else false +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + scrollToBeginning + (int maxSwipes) +

    +
    +
    + +
    + + + +
    +
    + +

    See scrollToBeginning(int, int)

    +
    +
    Returns
    +
    • true on scrolled else false +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + scrollToBeginning + (int maxSwipes, int steps) +

    +
    +
    + +
    + + + +
    +
    + +

    Scrolls to the beginning of a scrollable UI element. The beginning could be the top most + in case of vertical lists or the left most in case of horizontal lists. Caution is required + on devices configured with right to left languages like Arabic and Hebrew.

    +
    +
    Parameters
    + + + + + +
    stepsuse steps to control the speed, so that it may be a scroll, or fling
    +
    +
    +
    Returns
    +
    • true on scrolled else false +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + scrollToEnd + (int maxSwipes, int steps) +

    +
    +
    + +
    + + + +
    +
    + +

    Scrolls to the end of a scrollable UI element. The end could be the bottom most + in case of vertical controls or the right most for horizontal controls. Caution + is required on devices configured with right to left languages like Arabic and Hebrew.

    +
    +
    Parameters
    + + + + + +
    stepsuse steps to control the speed, so that it may be a scroll, or fling
    +
    +
    +
    Returns
    +
    • true on scrolled else false +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + boolean + + scrollToEnd + (int maxSwipes) +

    +
    +
    + +
    + + + +
    +
    + +

    See {@link UiScrollable#scrollToEnd(int, int)

    +
    +
    Returns
    +
    • true on scrolled else false +
    +
    +
    +
    Throws
    + + + + +
    UiObjectNotFoundException +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + void + + setAsHorizontalList + () +

    +
    +
    + +
    + + + +
    +
    + +

    Set the direction of swipes when performing scroll search +

    + +
    +
    + + + + +
    +

    + + public + + + + + void + + setAsVerticalList + () +

    +
    +
    + +
    + + + +
    +
    + +

    Set the direction of swipes when performing scroll search +

    + +
    +
    + + + + +
    +

    + + public + + + + + void + + setMaxSearchSwipes + (int swipes) +

    +
    +
    + +
    + + + +
    +
    + +

    #getChildByDescription(String, boolean) and #getChildByText(String, boolean) + use an arguments that specifies if scrolling is allowed while searching for the UI element. + The number of scrolls allowed to perform a search can be modified by this method. + The current value can be read by calling getMaxSearchSwipes()

    +
    +
    Parameters
    + + + + + +
    swipesis the number of search swipes until abort +
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + void + + setSwipeDeadZonePercentage + (double swipeDeadZonePercentage) +

    +
    +
    + +
    + + + +
    +
    + +

    Sets the percentage of a widget's size that's considered as a no touch zone when swiping. + + Dead zones are set as percentage of a widget's total width or height, denoting a margin + around the swipable area of the widget. Swipes must always start and + end inside this margin. + + This is important when the widget being swiped may not respond to the swipe if + started at a point too near to the edge. The default is 10% from either edge

    +
    +
    Parameters
    + + + + + +
    swipeDeadZonePercentageis a value between 0 and 1 +
    +
    + +
    +
    diff --git a/docs/html/tools/help/uiautomator/UiSelector.jd b/docs/html/tools/help/uiautomator/UiSelector.jd new file mode 100644 index 0000000..96d3fd8 --- /dev/null +++ b/docs/html/tools/help/uiautomator/UiSelector.jd @@ -0,0 +1,2088 @@ +page.title=UiSelector +parent.title=uiautomator +parent.link=index.html +@jd:body + + + +

    Class Overview

    +

    This class provides the mechanism for tests to describe the UI elements they + intend to target. A UI element has many properties associated with it such as + text value, content-description, class name and multiple state information like + selected, enabled, checked etc. Additionally UiSelector allows targeting of UI + elements within a specific display hierarchies to distinguish similar elements + based in the hierarchies they're in.

    + + + + + + + + + + + + + + + + + + + + + + +
    + + +

    Summary

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Public Constructors
    + + + + + + + + UiSelector() + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    Public Methods
    + + + + + + UiSelector + + checked(boolean val) + +
    Set the search criteria to match widgets that + are currently checked (usually for checkboxes).
    + +
    + + + + + + UiSelector + + childSelector(UiSelector selector) + +
    Adds a child UiSelector criteria to this selector.
    + +
    + + + + + + UiSelector + + className(String className) + +
    Set the search criteria to match the class property + for a widget (for example, "android.widget.Button").
    + +
    + + + + + <T> + UiSelector + + className(Class<T> type) + +
    Set the search criteria to match the class property + for a widget (for example, "android.widget.Button").
    + +
    + + + + + + UiSelector + + classNameMatches(String regex) + +
    Set the search criteria to match the class property + for a widget (for example, "android.widget.Button").
    + +
    + + + + + + UiSelector + + clickable(boolean val) + +
    Set the search criteria to match widgets that are clickable.
    + +
    + + + + + + UiSelector + + description(String desc) + +
    Set the search criteria to match the content-description + property for a widget.
    + +
    + + + + + + UiSelector + + descriptionContains(String desc) + +
    Set the search criteria to match the content-description + property for a widget.
    + +
    + + + + + + UiSelector + + descriptionMatches(String regex) + +
    Set the search criteria to match the content-description + property for a widget.
    + +
    + + + + + + UiSelector + + descriptionStartsWith(String desc) + +
    Set the search criteria to match the content-description + property for a widget.
    + +
    + + + + + + UiSelector + + enabled(boolean val) + +
    Set the search criteria to match widgets that are enabled.
    + +
    + + + + + + UiSelector + + focusable(boolean val) + +
    Set the search criteria to match widgets that are focusable.
    + +
    + + + + + + UiSelector + + focused(boolean val) + +
    Set the search criteria to match widgets that have focus.
    + +
    + + + + + + UiSelector + + fromParent(UiSelector selector) + +
    Adds a child UiSelector criteria to this selector which is used to + start search from the parent widget.
    + +
    + + + + + + UiSelector + + index(int index) + +
    Set the search criteria to match the widget by its node + index in the layout hierarchy.
    + +
    + + + + + + UiSelector + + instance(int instance) + +
    Set the search criteria to match the + widget by its instance number.
    + +
    + + + + + + UiSelector + + longClickable(boolean val) + +
    Set the search criteria to match widgets that are long-clickable.
    + +
    + + + + + + UiSelector + + packageName(String name) + +
    Set the search criteria to match the package name + of the application that contains the widget.
    + +
    + + + + + + UiSelector + + packageNameMatches(String regex) + +
    Set the search criteria to match the package name + of the application that contains the widget.
    + +
    + + + + + + UiSelector + + scrollable(boolean val) + +
    Set the search criteria to match widgets that are scrollable.
    + +
    + + + + + + UiSelector + + selected(boolean val) + +
    Set the search criteria to match widgets that + are currently selected.
    + +
    + + + + + + UiSelector + + text(String text) + +
    Set the search criteria to match the visible text displayed + for a widget (for example, the text label to launch an app).
    + +
    + + + + + + UiSelector + + textContains(String text) + +
    Set the search criteria to match the visible text displayed + for a widget (for example, the text label to launch an app).
    + +
    + + + + + + UiSelector + + textMatches(String regex) + +
    Set the search criteria to match the visible text displayed + for a widget (for example, the text label to launch an app).
    + +
    + + + + + + UiSelector + + textStartsWith(String text) + +
    Text property is usually the widget's visible text on the display.
    + +
    + + + + + + String + + toString() + +
    + + + + + + + + + + + + + + + +
    + [Expand] +
    Inherited Methods
    + +From class + + java.lang.Object + +
    + + +
    +
    + + +
    + + + + + + + + + + + + + + + + + + + + + + + + + + +

    Public Constructors

    + + + + + +
    +

    + + public + + + + + + + UiSelector + () +

    +
    +
    + +
    + + + +
    +
    + +

    + +
    +
    + + + + + + + + + + + + + +

    Public Methods

    + + + + + +
    +

    + + public + + + + + UiSelector + + checked + (boolean val) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match widgets that + are currently checked (usually for checkboxes). + + Typically, using this search criteria alone is not useful. + You should also include additional criteria, such as text, + content-description, or the class name for a widget. + + If no other search criteria is specified, and there is more + than one matching widget, the first widget in the tree + is selected.

    +
    +
    Parameters
    + + + + + +
    valValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + childSelector + (UiSelector selector) +

    +
    +
    + +
    + + + +
    +
    + +

    Adds a child UiSelector criteria to this selector. + + Use this selector to narrow the search scope to + child widgets under a specific parent widget.

    +
    +
    Returns
    +
    • UiSelector with this added search criterion
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + className + (String className) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match the class property + for a widget (for example, "android.widget.Button").

    +
    +
    Parameters
    + + + + + +
    classNameValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + className + (Class<T> type) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match the class property + for a widget (for example, "android.widget.Button").

    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    +
    +
    Since
    +
    • Android API Level 17
    +
    +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + classNameMatches + (String regex) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match the class property + for a widget (for example, "android.widget.Button").

    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    +
    +
    Since
    +
    • Android API Level 17
    +
    +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + clickable + (boolean val) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match widgets that are clickable. + + Typically, using this search criteria alone is not useful. + You should also include additional criteria, such as text, + content-description, or the class name for a widget. + + If no other search criteria is specified, and there is more + than one matching widget, the first widget in the tree + is selected.

    +
    +
    Parameters
    + + + + + +
    valValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + description + (String desc) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match the content-description + property for a widget. + + The content-description is typically used + by the Android Accessibility framework to + provide an audio prompt for the widget when + the widget is selected. The content-description + for the widget must match exactly + with the string in your input argument. + + Matching is case-sensitive.

    +
    +
    Parameters
    + + + + + +
    descValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + descriptionContains + (String desc) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match the content-description + property for a widget. + + The content-description is typically used + by the Android Accessibility framework to + provide an audio prompt for the widget when + the widget is selected. The content-description + for the widget must contain + the string in your input argument. + + Matching is case-insensitive.

    +
    +
    Parameters
    + + + + + +
    descValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + descriptionMatches + (String regex) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match the content-description + property for a widget. + + The content-description is typically used + by the Android Accessibility framework to + provide an audio prompt for the widget when + the widget is selected. The content-description + for the widget must match exactly + with the string in your input argument.

    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    +
    +
    Since
    +
    • Android API Level 17
    +
    +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + descriptionStartsWith + (String desc) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match the content-description + property for a widget. + + The content-description is typically used + by the Android Accessibility framework to + provide an audio prompt for the widget when + the widget is selected. The content-description + for the widget must start + with the string in your input argument. + + Matching is case-insensitive.

    +
    +
    Parameters
    + + + + + +
    descValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + enabled + (boolean val) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match widgets that are enabled. + + Typically, using this search criteria alone is not useful. + You should also include additional criteria, such as text, + content-description, or the class name for a widget. + + If no other search criteria is specified, and there is more + than one matching widget, the first widget in the tree + is selected.

    +
    +
    Parameters
    + + + + + +
    valValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + focusable + (boolean val) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match widgets that are focusable. + + Typically, using this search criteria alone is not useful. + You should also include additional criteria, such as text, + content-description, or the class name for a widget. + + If no other search criteria is specified, and there is more + than one matching widget, the first widget in the tree + is selected.

    +
    +
    Parameters
    + + + + + +
    valValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + focused + (boolean val) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match widgets that have focus. + + Typically, using this search criteria alone is not useful. + You should also include additional criteria, such as text, + content-description, or the class name for a widget. + + If no other search criteria is specified, and there is more + than one matching widget, the first widget in the tree + is selected.

    +
    +
    Parameters
    + + + + + +
    valValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + fromParent + (UiSelector selector) +

    +
    +
    + +
    + + + +
    +
    + +

    Adds a child UiSelector criteria to this selector which is used to + start search from the parent widget. + + Use this selector to narrow the search scope to + sibling widgets as well all child widgets under a parent.

    +
    +
    Returns
    +
    • UiSelector with this added search criterion
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + index + (int index) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match the widget by its node + index in the layout hierarchy. + + The index value must be 0 or greater. + + Using the index can be unreliable and should only + be used as a last resort for matching. Instead, + consider using the instance(int) method.

    +
    +
    Parameters
    + + + + + +
    indexValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + instance + (int instance) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match the + widget by its instance number. + + The instance value must be 0 or greater, where + the first instance is 0. + + For example, to simulate a user click on + the third image that is enabled in a UI screen, you + could specify a a search criteria where the instance is + 2, the className(String) matches the image + widget class, and enabled(boolean) is true. + The code would look like this: + + new UiSelector().className("android.widget.ImageView") + .enabled(true).instance(2); +

    +
    +
    Parameters
    + + + + + +
    instanceValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + longClickable + (boolean val) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match widgets that are long-clickable. + + Typically, using this search criteria alone is not useful. + You should also include additional criteria, such as text, + content-description, or the class name for a widget. + + If no other search criteria is specified, and there is more + than one matching widget, the first widget in the tree + is selected.

    +
    +
    Parameters
    + + + + + +
    valValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    +
    +
    Since
    +
    • Android API Level 17
    +
    +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + packageName + (String name) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match the package name + of the application that contains the widget.

    +
    +
    Parameters
    + + + + + +
    nameValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + packageNameMatches + (String regex) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match the package name + of the application that contains the widget.

    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    +
    +
    Since
    +
    • Android API Level 17
    +
    +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + scrollable + (boolean val) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match widgets that are scrollable. + + Typically, using this search criteria alone is not useful. + You should also include additional criteria, such as text, + content-description, or the class name for a widget. + + If no other search criteria is specified, and there is more + than one matching widget, the first widget in the tree + is selected.

    +
    +
    Parameters
    + + + + + +
    valValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + selected + (boolean val) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match widgets that + are currently selected. + + Typically, using this search criteria alone is not useful. + You should also include additional criteria, such as text, + content-description, or the class name for a widget. + + If no other search criteria is specified, and there is more + than one matching widget, the first widget in the tree + is selected.

    +
    +
    Parameters
    + + + + + +
    valValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + text + (String text) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match the visible text displayed + for a widget (for example, the text label to launch an app). + + The text for the widget must match exactly + with the string in your input argument. + Matching is case-sensitive.

    +
    +
    Parameters
    + + + + + +
    textValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + textContains + (String text) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match the visible text displayed + for a widget (for example, the text label to launch an app). + + The text for the widget must contain the string in + your input argument. Matching is case-sensitive.

    +
    +
    Parameters
    + + + + + +
    textValue to match
    +
    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + textMatches + (String regex) +

    +
    +
    + +
    + + + +
    +
    + +

    Set the search criteria to match the visible text displayed + for a widget (for example, the text label to launch an app). + + The text for the widget must match exactly + with the string in your input argument.

    +
    +
    Returns
    +
    • UiSelector with the specified search criteria
    +
    +
    +
    Since
    +
    • Android API Level 17
    +
    +
    +
    + + + + +
    +

    + + public + + + + + UiSelector + + textStartsWith + (String text) +

    +
    +
    + +
    + + + +
    +
    + +

    Text property is usually the widget's visible text on the display. + + Adding this to the search criteria indicates that the search performed + should match a widget with text value starting with the text parameter. + + The matching will be case-insensitive.

    +
    +
    Returns
    +
    • UiSelector with this added search criterion
    +
    + +
    +
    + + + + +
    +

    + + public + + + + + String + + toString + () +

    +
    +
    + +
    + + + +
    +
    + +

    + +
    +
    + + + + + + + + + + + diff --git a/docs/html/tools/help/uiautomator/UiWatcher.jd b/docs/html/tools/help/uiautomator/UiWatcher.jd new file mode 100644 index 0000000..b416fad --- /dev/null +++ b/docs/html/tools/help/uiautomator/UiWatcher.jd @@ -0,0 +1,78 @@ +page.title=UiWatcher +parent.title=uiautomator +parent.link=index.html +@jd:body + + +

    Represents a conditional watcher on the target device. To learn how to register a conditional + watcher, see UiDevice.registerWatcher(). +

    + +
    + +

    Summary

    + + + + + + + + + + + +
    Public Methods
    + abstract + + + + + boolean + + checkForCondition() + +
    The testing framework calls this handler method automatically when the framework + is unable to find a match using the UiSelector.
    + +
    + +
    + + + + + +

    Public Methods

    + + + +
    +

    + + public + + + abstract + + boolean + + checkForCondition + () +

    +
    + +
    +
    + +

    The testing framework calls this handler method automatically when the framework is unable to find a match using the UiSelector. When a match is not found after a predetermined time has elapsed, the framework calls the checkForCondition() method of all registered watchers on the device. You can use this method to handle known blocking issues that are preventing the test from proceeding. For example, you can check if a dialog appeared that is blocking the the test, then close the dialog or perform some other appropriate action to allow the test to continue.

    +
    +
    Returns
    +
    • true to indicate a matched condition, or false if no matching condition is found +
    +
    + +
    +
    diff --git a/docs/html/tools/help/uiautomator/index.jd b/docs/html/tools/help/uiautomator/index.jd new file mode 100644 index 0000000..38ba177 --- /dev/null +++ b/docs/html/tools/help/uiautomator/index.jd @@ -0,0 +1,177 @@ +page.title=uiautomator +parent.title=Tools +parent.link=index.html +@jd:body + +
    +
    +

    In this document

    + +
    +
    + +

    The {@code uiautomator} testing framework lets you test your user interface (UI) efficiently by creating automated functional UI testcases that can be run against your app on one or more devices.

    +

    For more information on testing with the {@code uiautomator} framework, see UI Testing.

    + +

    Syntax

    +

    To run your testcases on the target device, you can use the {@code adb shell} command to invoke the {@code uiautomator} tool. The syntax is: +

    +adb shell uiautomator runtest <jar> -c <test_class_or_method> [options]
+
    +

    +

    Here’s an example:

    +
    adb shell uiautomator runtest LaunchSettings.jar -c com.uia.example.my.LaunchSettings
    + +

    Command-line Options

    +

    The following table describes the subcommands and options for {@code uiautomator}.

    + +

    +Table 1. Command-line options for {@code uiautomator}

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    SubcommandOptionDescription
    runtest{@code <jar>}Required. The {@code <jar>} argument is the name of one or more JAR files that you deployed to the target device which contain your uiautomator testcases. You can list more than one JAR file by using a space as a separator.
    -c <test_class_or_method> Required. The {@code <test_class_or_method>} argument is a list of one or more specific test classes or test methods from the JARs that you want {@code uiautomator} to run.

    Each class or method must be fully qualified with the package name, in one of these formats: +

      +
    • {@code package_name.class_name}
      • +
    • {@code package_name.class_name#method_name}
      • +
    +You can list multiple classes or methods by using a space as a separator.

    --nohupRuns the test to completion on the device even if its parent process is terminated (for example, if the device is disconnected).
    -e <NAME> <VALUE>

    Specify other name-value pairs to be passed to test classes. May be repeated.

    Note: The {@code -e} options cannot be combined; you must prefix each option with a separate {@code -e} flag.

    -e debug [true|false]Wait for debugger to connect before starting.
    -e runner [CLASS]Use the specified test runner class instead. If unspecified, the {@code uiautomator} framework’s default runner will be used.
    dump[file]Generate an XML file with a dump of the current UI hierarchy. If a filepath is not specified, by default, the generated dump file is stored on the device in this location {@code /storage/sdcard0/window_dump.xml}.
    events Prints out accessibility events to the console until the connection to the device is terminated
    + +

    uiautomator API

    +

    The {@code uiautomator} API is bundled in the {@code uiautomator.jar} file under the {@code <android-sdk>/platforms/} directory. The API includes these key classes, interfaces, and exceptions that allow you to capture and manipulate UI components on the target app:

    + +

    Classes

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    ClassDescription
    {@code com.android.uiautomator.core.UiCollection}Used to enumerate a container's user interface (UI) elements for the purpose of counting, or targeting a sub elements by a child's text or description.
    {@code com.android.uiautomator.core.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 hardware button or pressing the Home and Menu buttons.
    {@code com.android.uiautomator.core.UiObject}Represents a user interface (UI) element.
    {@code com.android.uiautomator.core.UiScrollable}Provides support for searching for items in a scrollable UI container.
    {@code com.android.uiautomator.core.UiSelector}Represents a query for one or more target UI elements on a device screen.
    + +

    Interfaces

    + + + + + + + + + + + + + + + + + + + + + + +
    InterfaceDescription
    {@code com.android.uiautomator.core.UiWatcher}Represents a conditional watcher on the target device.
    {@code com.android.uiautomator.testrunner.IAutomationSupport}Provides auxiliary support for running test cases.
    {@code com.android.uiautomator.testrunner.UiAutomatorTestCase}Defines an environment for running multiple tests. All {@code uiautomator} test cases should extend this class.
    + +

    Exceptions

    + + + + + + + + + + + + +
    ExceptionDescription
    {@code com.android.uiautomator.core.UiObjectNotFoundException}Indicates when a a {@code UiSelector} could not be matched to any UI element displayed.
    + + + + + + diff --git a/docs/html/tools/testing/testing_ui.jd b/docs/html/tools/testing/testing_ui.jd new file mode 100644 index 0000000..8349d5c --- /dev/null +++ b/docs/html/tools/testing/testing_ui.jd @@ -0,0 +1,356 @@ +page.title=UI Testing +parent.title=Testing +parent.link=index.html +@jd:body + + + +

    +In addition to unit testing the individual components that make up your Android application (such as activities, services, and content providers), it is also important that you test the behavior of your application’s user interface (UI) when it is running on a device. UI testing ensures that your application returns the correct UI output in response to a sequence of user actions on a device, such as entering keyboard input or pressing toolbars, menus, dialogs, images, and other UI controls. +

    +

    +Functional or black-box UI testing does not require testers to know the internal implementation details of the app, only its expected output when a user performs a specific action or enters a specific input. This approach allows for better separation of development and testing roles in your organization. +

    +

    One common approach to UI testing is to run tests manually and verify that the app is behaving as expected. However, this approach can be time-consuming, tedious, and error-prone. A more efficient and reliable approach is to automate the UI testing with a software testing framework. Automated testing involves creating programs to perform testing tasks (test cases) to cover specific usage scenarios, and then using the testing framework to run the test cases automatically and in a repeatable manner.

    + +

    Overview

    +

    The Android SDK provides the following tools to support automated, functional UI testing on your application: +

      +
    • {@code uiautomatorviewer} - A GUI tool to scan and analyze the UI components of an Android application.
      • +
    • {@code uiautomator} - A Java library containing APIs to create customized functional UI tests, and an execution engine to automate and run the tests.
      • +

    + +

    To use these tools, you must have the following versions of the Android development tools installed: +

      +
    • Android SDK Tools, Revision 21 or higher
      • +
    • Android SDK Platform, API 16 or higher
      • +
    +

    + +

    Workflow for the the uiautomator testing framework

    +

    Here's a short overview of the steps required to automate UI testing: +

      +
    1. Prepare to test by installing the app on a test device, analyzing the app’s UI components, and ensuring that your application is accessible by the test automation framework.
      2. +
    2. Create automated tests to simulate specific user interactions on your application.
      3. +
    3. Compile your test cases into a JAR file and install it on your test device along with your app.
      4. +
    4. Run the tests and view the test results.
      5. +
    5. Correct any bugs or defects discovered in testing.
      6. +
    +

    + +

    Analyzing Your Application's UI

    +

    Before you start writing your test cases, it's helpful to familiarize yourself with the UI components (including the views and controls) of the targeted application. You can use the {@code uiautomatorviewer} tool to take a snapshot of the foreground UI screen on any Android device that is connected to your development machine. The {@code uiautomatorviewer} tool provides a convenient visual interface to inspect the layout hierarchy and view the properties of the individual UI components that are displayed on the test device. Using this information, you can later create {@code uiautomator} tests with selector objects that target specific UI components to test.

    + + + User interface of uiautomatorviewer tool + +

    + Figure 1. The {@code uiautomatorviewer} showing the captured interface of a test deviice. +

    + +

    To analyze the UI components of the application that you want to test:

    +
      +
    1. Connect your Android device to your development machine.
      2. +
    2. Open a terminal window and navigate to {@code <android-sdk>/tools/}.
      3. +
    3. Run the tool with this command:
      $ uiautomatorviewer
      4. +

    4. To capture a screen for analysis, click the Device Screenshot button in the GUI of the {@code uiautomatorviewer} tool.

      +

      Note: If you have more than one device connected, specify the device for screen capture by setting the {@code ANDROID_SERIAL} environment variable: +

        +
      1. Find the serial numbers for your connected devices by running this command:
        $ adb devices
        2. +
      2. Set the {@code ANDROID_SERIAL} environment variable to select the device to test: +
          +
        • In Windows: 
          set ANDROID_SERIAL=<device serial number>
          • +
        • In UNIX: 
          export ANDROID_SERIAL=<device serial number>
          • +
        +
        3. +
      +If you are connected to only a single device, you do not need to set the ANDROID_SERIAL environment variable.

      +
      5. +
    5. View the UI properties for your application: +
        +
      • Hover over the snapshot in the left-hand panel to see the UI components identified by the {@code uiautomatorviewer} tool. You can view the component’s properties listed in the lower right-hand panel, and the layout hierarchy in the upper right-hand panel.
        • +
      • Optionally, click on the Toggle NAF Nodes button to see UI components that are not accessible to the {@code uiautomator} testing framework. Only limited information may be available for these components.
        • +
      +
      6. +
    + +

    Preparing to Test

    +

    Before using the {@code uiautomator} testing framework, complete these pre-flight tasks: +

    +

    Load the application to a device

    +

    If you are reading this document, chances are that the Android application that you want to test has not been published yet. If you have a copy of the APK file, you can install the APK onto a test device by using the {@code adb} tool. To learn how to install an APK file using the {@code adb} tool, see the {@code adb} documentation.

    + +

    Identify the application’s UI components

    +

    Before writing your {@code uiautomator} tests, first identify the UI components in the application that you want to test. Typically, good candidates for testing are UI components that are visible and that users can interact with. The UI components should also have visible text labels, {@code android:contentDescription} values, or both. + +

    You can inspect the visible screen objects in an application conveniently by using the {@code uiautomatorviewer} tool. For more information about how to analyze an application screen with this tool, see the section Analyzing Your Application’s UI. For more information about the common types of UI components provided by Android, see User Interface.

    + +

    Ensure that the application is accessible

    +

    This step is required because the {@code uiautomator} tool depends on the accessibility features of the Android framework to execute your functional UI tests. You should include these minimum optimizations to support the {@code uiautomator} tool: +

      +
    • Use the {@code android:contentDescription} attribute to label the {@link android.widget.ImageButton}, {@link android.widget.ImageView}, {@link android.widget.CheckBox} and other user interface controls.
      • +
    • Provide an {@code android:hint} attribute instead of a content description for {@link android.widget.EditText} fields
      • +
    • Associate an android:hint attribute with any graphical icons used by controls that provide feedback to the user (for example, status or state information).
      • +
    • Make sure that all the user interface elements are accessible with a directional controller, such as a trackball or D-pad.
      • +
    • Use the {@code uiautomatorviewer} tool to ensure that the UI component is accessible to the testing framework. You can also test the application by turning on accessibility services like TalkBack and Explore by Touch, and try using your application using only directional controls.
      • +
    +

    + +

    For more information about implementing and testing accessibility, see Making Applications Accessible.

    + +

    Note: To identify the non-accessible components in the UI, click on the Toggle NAF Nodes option in the {@code uiautomatorviewer} tool.

    + +

    Generally, Android application developers get accessibility support for free, courtesy of the {@link android.view.View} and {@link android.view.ViewGroup} classes. However, some applications use custom view components to provide a richer user experience. Such custom components won't get the accessibility support that is provided by the standard Android UI components. If this applies to your application, ensure that the application developer exposes the custom drawn UI components to Android accessibility services, by implementing the {@link android.view.accessibility.AccessibilityNodeProvider} class. For more information about making custom view components accessible, see Making Applications Accessible.

    + +

    Configure your development environment

    +

    If you're developing in Eclipse, the Android SDK provides additional tools that help you write test cases using {@code uiautomator} and buiild your JAR file. In order to set up Eclipse to assist you, you need to create a project that includes the {@code uiautomator} client library, along with the Android SDK library. To configure Eclipse:

    +
      +
    1. Create a new Java project in Eclipse, and give your project a name that is relevant to the tests you’re about to create (for example, "MyAppNameTests"). In the project, you will create the test cases that are specific to the application that you want to test.
      2. +
    2. From the Project Explorer, right-click on the new project that you created, then select Properties > Java Build Path, and do the following: +
        +
      1. Click Add Library > JUnit then select JUnit3 to add JUnit support.
        2. +
      2. Click Add External JARs... and navigate to the SDK directory. Under the platforms directory, select the latest SDK version and add both the {@code uiautomator.jar} and {@code android.jar} files.
        3. +
      +
      3. +
    +

    If you did not configure Eclipse as your development environment, make sure that the {@code uiautomator.jar} and {@code android.jar} files from the {@code <android-sdk>/platforms/<sdk>} directory are in your Java class path.

    +

    Once you have completed these prerequisite tasks, you're almost ready to start creating your {@code uiautomator} tests. + +

    Creating uiautomator Tests

    +

    To build a test that runs in the {@code uiautomator} framework, create a test case that extends the {@code UiAutomatorTestCase} class. In Eclipse, the test case file goes under the {@code src} directory in your project. Later, you will build the test case as a JAR file, then copy this file to the test device. The test JAR file is not an APK file and resides separately from the application that you want to test on the device.

    + +

    Because the {@code UiAutomatorTestCase} class extends {@code junit.framework.TestCase}, you can use the JUnit {@code Assert} class to test that UI components in the app return the expected results. To learn more about JUnit, you can read the documentation on the junit.org home page.

    + +

    The first thing your test case should do is access the device that contains the target app. It’s also good practice to start the test from the Home screen of the device. From the Home screen (or some other starting location you’ve chosen in the target app), you can use the classes provided by the {@code uiautomator} API to simulate user actions and to test specific UI components. For an example of how to put together a {@code uiautomator} test case, see the sample test case.

    + +

    uiautomator API

    +

    The {@code uiautomator} API is bundled in the {@code uiautomator.jar} file under the {@code <android-sdk>/platforms/} directory. The API includes these key classes that allow you to capture and manipulate UI components on the target app:

    +
    +
    {@code UiDevice}
    +

    Represents the device state. In your tests, you can call methods on the {@code UiDevice} instance to check for the state of various properties, such as current orientation or display size. Your tests also can use the {@code UiDevice} instance to perform device level actions, such as forcing the device into a specific rotation, pressing the d-pad hardware button, or pressing the Home and Menu buttons.

    +

    To get an instance of {@code UiDevice} and simulate a Home button press: +

    +getUiDevice().pressHome();
+

    + +
    {@code UiSelector}
    +
    Represents a search criteria to query and get a handle on specific elements in the currently displayed UI. +If more than one matching element is found, the first matching element in the layout hierarchy is returned as the target {@code UiObject}. When constructing a {@code UiSelector}, you can chain together multiple properties to refine your search. If no matching UI element is found, a {@code UiAutomatorObjectNotFoundException} is thrown. You can use the {@code childSelector()} method to nest multiple {@code UiSelector} instances. For example, the following code example shows how to specify a search to find the first {@link android.widget.ListView} in the currently displayed UI, then search within that {@link android.widget.ListView} to find a UI element with the text property {@code Apps}. +
    +UiObject appItem = new UiObject(new UiSelector()
+   .className("android.widget.ListView").instance(1)
+   .childSelector(new UiSelector().text("Apps")));
+
    +
    + +
    {@code UiObject}
    +
    Represents a UI element. To create a {@code UiObject} instance, use a {@code UiSelector} that describes how to search for, or select, the UI element. +

    The following code example shows how to construct {@code UiObject} instances that represent a Cancel button and a OK button in your application.

    +
    +UiObject cancelButton = new UiObject(new UiSelector().text("Cancel"));
+UiObject okButton = new UiObject(new UiSelector().text("OK"));
+
    +

    You can reuse the {@code UiObject} instances that you have created in other parts of your app testing, as needed. Note that the {@code uiautomator} test framework searches the current display for a match every time your test uses a {@code UiObject} instance to click on a UI element or query a property.

    +

    In the following code example, the {@code uiautomator} test framework searches for a UI element with the text property {@code OK}. If a match is found and if the element is enabled, the framework simulates a user click action on the element.

    +
    +if(okButton.exists() && okButton.isEnabled()) 
+{
+  okButton.click();
+}
+
    +

    You can also restrict the search to find only elements of a specific class. For example, to find matches of the {@link android.widget.Button} class:

    +
    +UiObject cancelButton = new UiObject(new UiSelector().text("Cancel")
+   .className("android.widget.Button"));
+UiObject okButton = new UiObject(new UiSelector().text("OK")
+   .className("android.widget.Button"));
+
    +
    + +
    {@code UiCollection}
    +
    Represents a collection of items, for example songs in a music album or a list of emails in an inbox. Similar to a {@code UiObject}, you construct a {@code UiCollection} instance by specifying a {@code UiSelector}. The {@code UiSelector} for a {@code UiCollection} should search for a UI element that is a container or wrapper of other child UI elements (such as a layout view that contains child UI elements). For example, the following code snippet shows how to construct a {@code UiCollection} to represent a video album that is displayed within a {@link android.widget.FrameLayout}: +
    +UiCollection videos = new UiCollection(new UiSelector()
+   .className("android.widget.FrameLayout"));
+
    +

    If the videos are listed within a {@link android.widget.LinearLayout} view, and you want to to retrieve the number of videos in this collection:

    +
    +int count = videos.getChildCount(new UiSelector()
+   .className("android.widget.LinearLayout"));
+
    +

    If you want to find a specific video that is labeled with the text element {@code Cute Baby Laughing} from the collection and simulate a user-click on the video:

    +
    +UiObject video = videos.getChildByText(new UiSelector()
+   .className("android.widget.LinearLayout"), "Cute Baby Laughing");
+video.click();
+
    +

    Similarly, you can simulate other user actions on the UI object. For example, if you want +to simulate selecting a checkbox that is associated with the video:

    +
    +UiObject checkBox = video.getChild(new UiSelector()
+   .className("android.widget.Checkbox"));
+if(!checkBox.isSelected()) checkbox.click();
+
    +
    + +
    {@code UiScrollable}
    +
    Represents a scrollable collection of UI elements. You can use the {@code UiScrollable} class to simulate vertical or horizontal scrolling across a display. This technique is helpful when a UI element is positioned off-screen and you need to scroll to bring it into view. +

    For example, the following code shows how to simulate scrolling down the Settings menu and clicking on an About tablet option:

    +
    +UiScrollable settingsItem = new UiScrollable(new UiSelector()
+   .className("android.widget.ListView"));
+UiObject about = settingsItem.getChildByText(new UiSelector()
+   .className("android.widget.LinearLayout"), "About  tablet");
+about.click()
+
    +
    +
    +

    For more information about these APIs, see the {@code uiautomator} reference.

    + +

    A sample uiautomator test case

    +

    The following code example shows a simple test case which simulates a user bringing up the Settings app in a stock Android device. The test case mimics all the steps that a user would typically take to perform this task, including opening the Home screen, launching the All Apps screen, scrolling to the Settings app icon, and clicking on the icon to enter the Settings app.

    +
    +package com.uia.example.my;
+
+// Import the uiautomator libraries
+import com.android.uiautomator.core.UiObject;
+import com.android.uiautomator.core.UiObjectNotFoundException;
+import com.android.uiautomator.core.UiScrollable;
+import com.android.uiautomator.core.UiSelector;
+import com.android.uiautomator.testrunner.UiAutomatorTestCase;
+
+public class LaunchSettings extends UiAutomatorTestCase {   
+
+   public void testDemo() throws UiObjectNotFoundException {   
+      
+      // Simulate a short press on the HOME button.
+      getUiDevice().pressHome();
+      
+      // We’re now in the home screen. Next, we want to simulate 
+      // a user bringing up the All Apps screen.
+      // If you use the uiautomatorviewer tool to capture a snapshot 
+      // of the Home screen, notice that the All Apps button’s 
+      // content-description property has the value “Apps”.  We can 
+      // use this property to create a UiSelector to find the button. 
+      UiObject allAppsButton = new UiObject(new UiSelector()
+         .description("Apps"));
+      
+      // Simulate a click to bring up the All Apps screen.
+      allAppsButton.clickAndWaitForNewWindow();
+      
+      // In the All Apps screen, the Settings app is located in 
+      // the Apps tab. To simulate the user bringing up the Apps tab,
+      // we create a UiSelector to find a tab with the text 
+      // label “Apps”.
+      UiObject appsTab = new UiObject(new UiSelector()
+         .text("Apps"));
+      
+      // Simulate a click to enter the Apps tab.
+      appsTab.click();
+
+      // Next, in the apps tabs, we can simulate a user swiping until
+      // they come to the Settings app icon.  Since the container view 
+      // is scrollable, we can use a UiScrollable object.
+      UiScrollable appViews = new UiScrollable(new UiSelector()
+         .scrollable(true));
+      
+      // Set the swiping mode to horizontal (the default is vertical)
+      appViews.setAsHorizontalList();
+      
+      // Create a UiSelector to find the Settings app and simulate      
+      // a user click to launch the app. 
+      UiObject settingsApp = appViews.getChildByText(new UiSelector()
+         .className(android.widget.TextView.class.getName()), 
+         "Settings");
+      settingsApp.clickAndWaitForNewWindow();
+      
+      // Validate that the package name is the expected one
+      UiObject settingsValidation = new UiObject(new UiSelector()
+         .packageName("com.android.settings"));
+      assertTrue("Unable to detect Settings", 
+         settingsValidation.exists());   
+  }   
+}
+
    + +

    Building and Deploying Your uiautomator Tests

    +

    Once you have coded your test, follow these steps to build and deploy your test JAR to your target Android test device:

    +
      +
    1. Create the required build configuration files to build the output JAR. To generate the build configuration files, open a terminal and run the following command: +
      <android-sdk>/tools/android uitest-project -n <name> -t 1 -p <path>
      +The {@code <name>} is the name of the project that contains your {@code uiautomator} test source files, and the {@code <path>} is the path to the corresponding project directory. +
      2. +
    2. From the command line, set the {@code ANDROID_HOME} variable: +
        +
      • In Windows: +
        set ANDROID_HOME=<path_to_your_sdk>
        +
        • +
      • In UNIX: +
        export ANDROID_HOME=<path_to_your_sdk>
        +
        • +
      +
      3. +
    3. Go to the project directory where your {@code build.xml} file is located and build your test JAR. 
      ant build
      4. +
    4. Deploy your generated test JAR file to the test device by using the {@code adb push} command: 
      adb push <path_to_output_jar> /data/local/tmp/
      +

      Here’s an example: 

      adb push ~/dev/workspace/LaunchSettings/bin/LaunchSettings.jar /data/local/tmp/

      +
      5. +
    + +

    Running uiautomator Tests

    +

    Here’s an example of how to run a test that is implemented in the {@code LaunchSettings.jar} file. The tests are bundled in the {@code com.uia.example.my} package:

    +
    adb shell uiautomator runtest LaunchSettings.jar -c com.uia.example.my.LaunchSettings
    +

    To learn more about the syntax, subcommands, and options for {@code uiautomator}, see the {@code uiautomator} reference.

    + + +

    Best Practices

    +

    Here are some best practices for functional UI testing with the {@code uiautomator} framework:

    +
      +
    • Ensure that you validate the same UI functions on your application across the various types of devices that your application might run on (for example, devices with different screen densities).
      • +
    • You should also test your UI against common scenarios such as in-coming phone calls, network interruptions, and user-initiated switching to other applications on the device.
      • +
    + diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs index cca9433..e9e1b09 100644 --- a/docs/html/tools/tools_toc.cs +++ b/docs/html/tools/tools_toc.cs @@ -93,6 +93,10 @@ Accessibility Testing +
  • + + UI Testing +
  • What To Test @@ -163,6 +167,20 @@ class="en">MonkeyRunner
  • Systrace
  • Tracer for OpenGL ES
  • Traceview
    • +
  • +
    uiautomator
    + +
  • zipalign
    • -- cgit v1.1