An exposed registry instance that holds a reference to the instrumentation running in the
+ process and it's arguments. Also provides an easy way for callers to get a hold of
+ instrumentation, application context and instrumentation arguments Bundle.
+
Returns a copy of instrumentation arguments Bundle. Use this to get a Bundle
+ containing the command line arguments passed to Instrumentation into your test.
+
+ This Bundle is not guaranteed to be present under all instrumentations.
+
An exception which indicates that a Matcher matched multiple views in the hierarchy when
+ only one view was expected. It should be called only from the main thread.
+
+ Contains details about the matcher and the current view hierarchy to aid in debugging.
+
+
+ Since this is usually an unrecoverable error this exception is a runtime exception.
+
+
+ References to the view and failing matcher are purposefully not included in the state of this
+ object - since it will most likely be created on the UI thread and thrown on the instrumentation
+ thread, it would be invalid to touch the view on the instrumentation thread. Also the view
+ hierarchy may have changed since exception creation (leading to more confusion).
+
+
+ public
+ static
+
+
+
+ AppNotIdleException
+
+ create
+ (List<String> idleConditions, int loopCount, int seconds)
+
+
+
+
+
+
+
+
+
+
+
+
+
Creates a new AppNotIdleException suitable for erroring out a test case.
+
+ This should be called only from the main thread if the app does not idle out within the
+ specified duration.
+
+
Parameters
+
+
+
idleConditions
+
list of idleConditions that failed to become idle.
+
+
+
loopCount
+
number of times it was tried to check if they became idle.
+
+
+
seconds
+
number of seconds that was tried before giving up.
+
+
+
+
+
Returns
+
a AppNotIdleException suitable to be thrown on the instrumentation thread.
+
An interface to interact with data displayed in AdapterViews.
+
+ This interface builds on top of ViewInteraction and should be the preferred way to
+ interact with elements displayed inside AdapterViews.
+
+
+ This is necessary because an AdapterView may not load all the data held by its Adapter into the
+ view hierarchy until a user interaction makes it necessary. Also it is more fluent / less brittle
+ to match upon the data object being rendered into the display then the rendering itself.
+
+
+ By default, a DataInteraction takes place against any AdapterView found within the current
+ screen, if you have multiple AdapterView objects displayed, you will need to narrow the selection
+ by using the inAdapterView method.
+
+
+ The check and perform method operate on the top level child of the adapter view, if you need to
+ operate on a subview (eg: a Button within the list) use the onChildView method before calling
+ perform or check.
+
+ Use a different AdapterViewProtocol if the Adapter implementation does not
+ satisfy the AdapterView contract like (@code ExpandableListView)
+
+
+
+
+
Entry point to the Espresso framework. Test authors can initiate testing by using one of the on*
+ methods (e.g. onView) or perform top-level user actions (e.g. pressBack).
+
Creates an DataInteraction for a data object displayed by the application. Use this
+ method to load (into the view hierarchy) items from AdapterView widgets (e.g. ListView).
Creates a ViewInteraction for a given view. Note: the view has
+ to be part of the view hierarchy. This may not be the case if it is rendered as part of
+ an AdapterView (e.g. ListView). If this is the case, use Espresso.onData to load the view
+ first.
Opens the overflow menu displayed within an ActionBar.
+
+
This works with both native and SherlockActionBar ActionBars.
+
+
Note the significant differences of UX between ActionMode and ActionBars with respect to
+ overflows. If a hardware menu key is present, the overflow icon is never displayed in
+ ActionBars and can only be interacted with via menu key presses.
+
Opens the overflow menu displayed in the contextual options of an ActionMode.
+
+
This works with both native and SherlockActionBar action modes.
+
+
Note the significant difference in UX between ActionMode and ActionBar overflows -
+ ActionMode will always present an overflow icon and that icon only responds to clicks.
+ The menu button (if present) has no impact on it.
+
Registers one or more IdlingResources with the framework. It is expected, although not
+ strictly required, that this method will be called at test setup time prior to any interaction
+ with the application under test. When registering more than one resource, ensure that each has
+ a unique name. If any of the given resources is already registered, a warning is logged.
Handle the given error in a manner that makes sense to the environment in which the test is
+ executed (e.g. take a screenshot, output extra debug info, etc). Upon handling, most handlers
+ will choose to propagate the error.
+
Allows users fine grain control over idling policies.
+
+ Espresso's default idling policies are suitable for most usecases - however
+ certain execution environments (like the ARM emulator) might be very slow.
+ This class allows users the ability to adjust defaults to sensible values
+ for their environments.
+
+ An implementation of IdlingResource that determines idleness by maintaining an internal
+ counter.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Class Overview
+
Represents a resource of an application under test which can cause asynchronous background work
+ to happen during test execution (e.g. an intent service that processes a button click). By
+ default, Espresso synchronizes all view operations with the UI thread as well as
+ AsyncTasks; however, it has no way of doing so with "hand-made" resources. In such cases, test
+ authors can register the custom resource and Espresso will wait for the resource to
+ become idle prior to executing a view operation.
+
+ Important Note: it is assumed that the resource stays idle most of the time.
+
Returns true if resource is currently idle. Espresso will always call this
+ method from the main thread, therefore it should be non-blocking and return immediately.
+
with its implementation of IdlingResource.ResourceCallback so it can be notified asynchronously
+ that your resource is idle
+
from the main thread, but you are free to execute the callback's onTransitionToIdle from
+ any thread
+
once (when it is initially given a reference to your IdlingResource)
+
+
+ You only need to call this upon transition from busy to idle - if the resource is already idle
+ when the method is called invoking the call back is optional and has no significant impact.
+
Indicates that an IdlingResource, which has been registered with the framework, has not
+ idled within the allowed time.
+
+ Since it is not safe to proceed with test execution while the registered resource is busy (as it
+ is likely to cause inconsistent results in the test), this is an unrecoverable error. The test
+ author should verify that the IdlingResource interface has been implemented correctly.
+
Indicates that a given matcher did not match any elements in the view hierarchy.
+
+ Contains details about the matcher and the current view hierarchy to aid in debugging.
+
+
+ Since this is usually an unrecoverable error this exception is a runtime exception.
+
+
+ References to the view and failing matcher are purposefully not included in the state of this
+ object - since it will most likely be created on the UI thread and thrown on the instrumentation
+ thread, it would be invalid to touch the view on the instrumentation thread. Also the view
+ hierarchy may have changed since exception creation (leading to more confusion).
+
Indicates that an exception occurred while performing a ViewAction on the UI thread.
+
+ A description of the ViewAction, the view being performed on and the cause are included
+ in the error. Note: FailureHandlers can mutate the exception later to make it more user
+ friendly.
+
+ This is generally not recoverable so it is thrown on the instrumentation thread.
+
Represents a root view in the application and optionally the layout params of the window holding
+ it.
+
+ This class is used internally to determine which view root to run user provided matchers against
+ it is not part of the public api.
+
Provides base-level UI operations (such as injection of MotionEvents) that can be used to
+ build user actions such as clicks, scrolls, swipes, etc. This replaces parts of the android
+ Instrumentation class that provides similar functionality. However, it provides a more advanced
+ synchronization mechanism for test actions. The key differentiators are:
+
+
test actions are assumed to be called on the main thread
+
after a test action is initiated, execution blocks until all messages in the main message
+ queue have been cleared.
+
Types a string into the application using series of KeyEvents. It is up to the
+ implementor to decide how to map the string to KeyEvent objects. if you need specific
+ control over the key events generated use injectKeyEvent(KeyEvent).
Loops the main thread for a specified period of time.
+
+ Control may not return immediately, instead it'll return after the time has passed and the
+ queue is in an idle state again.
Loops the main thread until the application goes idle.
+
+ An empty task is immediately inserted into the task queue to ensure that if we're idle at this
+ moment we'll return instantly.
+
Responsible for performing an interaction on the given View element.
+
+ This is part of the test framework public API - developers are free to write their own ViewAction
+ implementations when necessary. When implementing a new ViewAction, follow these rules:
+
+
Inject motion events or key events via the UiController to simulate user interactions.
+
Do not mutate the view directly via setter methods and other state changing methods on the
+ view parameter.
+
Do not throw AssertionErrors. Assertions belong in ViewAssertion classes.
+
View action code will executed on the UI thread, therefore you should not block, perform
+ sleeps, or perform other expensive computations.
+
The test framework will wait for the UI thread to be idle both before and after perform() is
+ called. This means that the action is guaranteed to be synchronized with any other view
+ operations.
+
Downcasting the View object to an expected subtype is allowed, so long as the object
+ expresses the subtype matches the constraints as specified in getConstraints.
+
A mechanism for ViewActions to specify what type of views they can operate on.
+
+ A ViewAction can demand that the view passed to perform meets certain constraints. For example
+ it may want to ensure the view is already in the viewable physical screen of the device or is
+ of a certain type.
+
+
Returns
+
a
+ Matcher that will be tested prior to calling perform.
+
Returns a description of the view action. The description should not be overly long and should
+ fit nicely in a sentence like: "performing %description% action on view with id ..."
+
Responsible for performing assertions on a View element.
+
+ This is considered part of the test framework public API - developers are free to write their own
+ assertions as long as they meet the following requirements:
+
+
Do not mutate the passed in view.
+
Throw junit.framework.AssertionError when the view assertion does not hold.
+
Implementation runs on the UI thread - so it should not do any blocking operations
+
Downcasting the view to a specific type is allowed, provided there is a test that view is an
+ instance of that type before downcasting. If not, an AssertionError should be thrown.
+
It is encouraged to access non-mutating methods on the view to perform assertion.
+
+
+
+ Strongly consider using a existing ViewAssertion via the ViewAssertions utility class before
+ writing your own assertion.
+
Immediately locates a single view within the provided view hierarchy.
+
+ If multiple views match, or if no views match the appropriate exception is thrown.
+
+
Returns
+
A singular view which matches the matcher we were constructed with.
Provides the primary interface for test authors to perform actions or asserts on views.
+
+ Each interaction is associated with a view identified by a view matcher. All view actions and
+ asserts are performed on the UI thread (thus ensuring sequential execution). The same goes for
+ retrieval of views (this is done to ensure that view state is "fresh" prior to execution of each
+ operation).
+
Performs the given action(s) on the view selected by the current view matcher. If more than one
+ action is provided, actions are executed in the order provided with precondition checks running
+ prior to each action.
+
+
Parameters
+
+
+
viewActions
+
one or more actions to execute.
+
+
+
+
+
Returns
+
this interaction for further perform/verification calls.
+
A mechanism for ViewActions to specify what type of views they can operate on.
+
+ A ViewAction can demand that the view passed to perform meets certain constraints. For example
+ it may want to ensure the view is already in the viewable physical screen of the device or is
+ of a certain type.
+
+
Returns
+
a
+ Matcher that will be tested prior to calling perform.
+
Returns a description of the view action. The description should not be overly long and should
+ fit nicely in a sentence like: "performing %description% action on view with id ..."
+
A holder that associates a data object from an AdapterView with a token the
+ AdapterViewProtocol can use to force that data object to be rendered as a child or deeper
+ descendant of the adapter view.
+
+ A token the implementor of AdapterViewProtocol can use to force the adapterView to display
+ this data object as a child or deeper descendant in it.
+
+
+
+
+ This field is deprecated.
+ use getData() instead.
+
+
+
One of the objects the AdapterView is exposing to the user.
+
+
+
+
+
+
+
+
+
+
+
+
+ public
+
+ final
+ Object
+
+ opaqueToken
+
+
+
+
+
+
+
+
+
+
+
+
+
A token the implementor of AdapterViewProtocol can use to force the adapterView to display
+ this data object as a child or deeper descendant in it. Equal opaqueToken point to the same
+ data object on the AdapterView.
+
A sadly necessary layer of indirection to interact with AdapterViews.
+
+ Generally any subclass should respect the contracts and behaviors of its superclass. Otherwise
+ it becomes impossible to work generically with objects that all claim to share a supertype - you
+ need special cases to perform the same operation 'owned' by the supertype for each sub-type. The
+ 'is - a' relationship is broken.
+
+
+
+ Android breaks the Liskov substitution principal with ExpandableListView - you can't use
+ getAdapter(), getItemAtPosition(), and other methods common to AdapterViews on an
+ ExpandableListView because an ExpandableListView isn't an adapterView - they just share a lot of
+ code.
+
+
+
+ This interface exists to work around this wart (which sadly is copied in other projects too) and
+ lets the implementor translate Espresso's needs and manipulations of the AdapterView into calls
+ that make sense for the given subtype and context.
+
+
+
+ If you have to implement this to talk to widgets your own project defines - I'm sorry.
+
+ A holder that associates a data object from an AdapterView with a token the
+ AdapterViewProtocol can use to force that data object to be rendered as a child or deeper
+ descendant of the adapter view.
+
+
+
+
Returns all data this AdapterViewProtocol can find within the given AdapterView.
+
+
+ Any AdaptedData returned by this method can be passed to makeDataRenderedWithinView and the
+ implementation should make the AdapterView bring that data item onto the screen.
+
+
+
Parameters
+
+
+
adapterView
+
the AdapterView we want to interrogate the contents of.
+
+
+
+
+
Returns
+
an Iterable of AdaptedDatas representing all data the implementation sees in
+ this view
+
+
+
Throws
+
+
+
IllegalArgumentException
+
if the implementation doesn't know how to manipulate the given
+ adapter view.
+
Returns the data object this particular view is rendering if possible.
+
+
+ Implementations are expected to create a relationship between the data in the AdapterView and
+ the descendant views of the AdapterView that obeys the following conditions:
+
+
+
+
For each descendant view there exists either 0 or 1 data objects it is rendering.
+
For each data object the AdapterView there exists either 0 or 1 descendant views which
+ claim to be rendering it.
+ It would be expected that getDataRenderedByView(adapter, LinearLayout) would return the
+ PersonObject. If it were called instead with the TextView or ImageView it would return
+ Object.absent().
+
+
+
Parameters
+
+
+
adapterView
+
the adapterview hosting the data.
+
+
+
descendantView
+
a view which is a child, grand-child, or deeper descendant of adapterView
+
+
+
+
+
Returns
+
an optional data object the descendant view is rendering.
+
+
+
Throws
+
+
+
IllegalArgumentException
+
if this protocol cannot interrogate this class of adapterView
+
Requests that a particular piece of data held in this AdapterView is actually rendered by it.
+
+
+ After calling this method it expected that there will exist some descendant view of adapterView
+ for which calling getDataRenderedByView(adapterView, descView).get() == data.data is true.
+
+
+
+ Note: this need not happen immediately. EG: an implementor handling ListView may call
+ listView.smoothScrollToPosition(data.opaqueToken) - which kicks off an animated scroll over
+ the list to the given position. The animation may be in progress after this call returns. The
+ only guarantee is that eventually - with no further interaction necessary - this data item
+ will be rendered as a child or deeper descendant of this AdapterView.
+
+
+
Parameters
+
+
+
adapterView
+
the adapterView hosting the data.
+
+
+
data
+
an AdaptedData instance retrieved by a prior call to getDataInAdapterView
+
+
+
+
+
Throws
+
+
+
IllegalArgumentException
+
if this protocol cannot manipulate adapterView or if data is
+ not owned by this AdapterViewProtocol.
+
A mechanism for ViewActions to specify what type of views they can operate on.
+
+ A ViewAction can demand that the view passed to perform meets certain constraints. For example
+ it may want to ensure the view is already in the viewable physical screen of the device or is
+ of a certain type.
+
+
Returns
+
a
+ Matcher that will be tested prior to calling perform.
+
Returns a description of the view action. The description should not be overly long and should
+ fit nicely in a sentence like: "performing %description% action on view with id ..."
+
A mechanism for ViewActions to specify what type of views they can operate on.
+
+ A ViewAction can demand that the view passed to perform meets certain constraints. For example
+ it may want to ensure the view is already in the viewable physical screen of the device or is
+ of a certain type.
+
+
Returns
+
a
+ Matcher that will be tested prior to calling perform.
+
Returns a description of the view action. The description should not be overly long and should
+ fit nicely in a sentence like: "performing %description% action on view with id ..."
+
A mechanism for ViewActions to specify what type of views they can operate on.
+
+ A ViewAction can demand that the view passed to perform meets certain constraints. For example
+ it may want to ensure the view is already in the viewable physical screen of the device or is
+ of a certain type.
+
+
Returns
+
a
+ Matcher that will be tested prior to calling perform.
+
Returns a description of the view action. The description should not be overly long and should
+ fit nicely in a sentence like: "performing %description% action on view with id ..."
+
A mechanism for ViewActions to specify what type of views they can operate on.
+
+ A ViewAction can demand that the view passed to perform meets certain constraints. For example
+ it may want to ensure the view is already in the viewable physical screen of the device or is
+ of a certain type.
+
+
Returns
+
a
+ Matcher that will be tested prior to calling perform.
+
Returns a description of the view action. The description should not be overly long and should
+ fit nicely in a sentence like: "performing %description% action on view with id ..."
+
A mechanism for ViewActions to specify what type of views they can operate on.
+
+ A ViewAction can demand that the view passed to perform meets certain constraints. For example
+ it may want to ensure the view is already in the viewable physical screen of the device or is
+ of a certain type.
+
+
Returns
+
a
+ Matcher that will be tested prior to calling perform.
+
Returns a description of the view action. The description should not be overly long and should
+ fit nicely in a sentence like: "performing %description% action on view with id ..."
+
Invokes onClick of a link within a TextView (made with Linkify or via another method).
+ Why not issue a real click event to the screen? Unfortunately, it does not seem to be possible
+ (at least using public APIs) to determine the location of the link on the screen.
+
A mechanism for ViewActions to specify what type of views they can operate on.
+
+ A ViewAction can demand that the view passed to perform meets certain constraints. For example
+ it may want to ensure the view is already in the viewable physical screen of the device or is
+ of a certain type.
+
+
Returns
+
a
+ Matcher that will be tested prior to calling perform.
+
Returns a description of the view action. The description should not be overly long and should
+ fit nicely in a sentence like: "performing %description% action on view with id ..."
+
A mechanism for ViewActions to specify what type of views they can operate on.
+
+ A ViewAction can demand that the view passed to perform meets certain constraints. For example
+ it may want to ensure the view is already in the viewable physical screen of the device or is
+ of a certain type.
+
+
Returns
+
a
+ Matcher that will be tested prior to calling perform.
+
Returns a description of the view action. The description should not be overly long and should
+ fit nicely in a sentence like: "performing %description% action on view with id ..."
+
A mechanism for ViewActions to specify what type of views they can operate on.
+
+ A ViewAction can demand that the view passed to perform meets certain constraints. For example
+ it may want to ensure the view is already in the viewable physical screen of the device or is
+ of a certain type.
+
+
Returns
+
a
+ Matcher that will be tested prior to calling perform.
+
Returns a description of the view action. The description should not be overly long and should
+ fit nicely in a sentence like: "performing %description% action on view with id ..."
+
+
+ public
+ static
+ final
+ Tapper.Status
+
+ FAILURE
+
+
+
+
+
+
+
+
+
+
+
+
+
Injecting the event was a complete failure.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ public
+ static
+ final
+ Tapper.Status
+
+ SUCCESS
+
+
+
+
+
+
+
+
+
+
+
+
+
The Tap action completed successfully.
+
+
+
+
+
+
+
+
+
+
+
+
+
+ public
+ static
+ final
+ Tapper.Status
+
+ WARNING
+
+
+
+
+
+
+
+
+
+
+
+
+
The action seemed to have completed - but may have been misinterpreted
+ by the application. (For Example a TAP became a LONG PRESS by measuring
+ its time between the down and up events).
+
Constructs TypeTextAction with given string. If the string is empty it results in no-op
+ (nothing is typed). By default this action sends a tap event to the center of the view to
+ attain focus before typing.
A mechanism for ViewActions to specify what type of views they can operate on.
+
+ A ViewAction can demand that the view passed to perform meets certain constraints. For example
+ it may want to ensure the view is already in the viewable physical screen of the device or is
+ of a certain type.
+
+
Returns
+
a
+ Matcher that will be tested prior to calling perform.
+
Returns a description of the view action. The description should not be overly long and should
+ fit nicely in a sentence like: "performing %description% action on view with id ..."
+
Returns an action that performs a single click on the view.
+
+ If the click takes longer than the 'long press' duration (which is possible) the provided
+ rollback action is invoked on the view and a click is attempted again.
+
+ This is only necessary if the view being clicked on has some different behaviour for long press
+ versus a normal tap.
+
+ For example - if a long press on a particular view element opens a popup menu -
+ ViewActions.pressBack() may be an acceptable rollback action.
+
+
+ View constraints:
+
Returns an action that opens a link matching the given link text and uri matchers. The action
+ is performed by invoking the link's onClick method (as opposed to actually issuing a click on
+ the screen).
+
+
+ View preconditions:
+
Returns an action that presses the current action button (next, done, search, etc) on the IME
+ (Input Method Editor). The selected view will have its onEditorAction method called.
+
Returns an action that performs a swipe top-to-bottom across the horizontal center of the view.
+ The swipe doesn't start at the very edge of the view, but has a bit of offset.
+
+ View constraints:
+
Returns an action that performs a swipe right-to-left across the vertical center of the
+ view. The swipe doesn't start at the very edge of the view, but is a bit offset.
+
+ View constraints:
+
Returns an action that performs a swipe left-to-right across the vertical center of the
+ view. The swipe doesn't start at the very edge of the view, but is a bit offset.
+
+ View constraints:
+
Returns an action that performs a swipe bottom-to-top across the horizontal center of the view.
+ The swipe doesn't start at the very edge of the view, but has a bit of offset.
+
+ View constraints:
+
Returns an action that selects the view (by clicking on it) and types the provided string into
+ the view. Appending a \n to the end of the string translates to a ENTER key event. Note: this
+ method performs a tap on the view before typing to force the view into focus, if the view
+ already contains text this tap may place the cursor at an arbitrary position within the text.
+
+
+ View preconditions:
+
Returns an action that types the provided string into the view.
+ Appending a \n to the end of the string translates to a ENTER key event. Note: this method
+ does not change cursor position in the focused view - text is inserted at the location where
+ the cursor is currently pointed.
+
+ View preconditions:
+
+ A holder that associates a data object from an AdapterView with a token the
+ AdapterViewProtocol can use to force that data object to be rendered as a child or deeper
+ descendant of the adapter view.
+
+
+
+
Returns a generic ViewAssertion that asserts that the descendant views selected by the
+ selector match the specified matcher.
+
+ Example: onView(rootView).check(selectedDescendantsMatch(
+ not(isAssignableFrom(TextView.class)), hasContentDescription()));
+
Espresso's default FailureHandler. If this does not fit your needs, feel free to provide
+ your own implementation via Espresso.setFailureHandler(FailureHandler).
+
Handle the given error in a manner that makes sense to the environment in which the test is
+ executed (e.g. take a screenshot, output extra debug info, etc). Upon handling, most handlers
+ will choose to propagate the error.
+
Provides the root View of the top-most Window, with which the user can interact. View is
+ guaranteed to be in a stable state - i.e. not pending any updates from the application.
+
+ This provider can only be accessed from the main thread.
+
Immediately locates a single view within the provided view hierarchy.
+
+ If multiple views match, or if no views match the appropriate exception is thrown.
+
+
Returns
+
A singular view which matches the matcher we were constructed with.
An implementation of IdlingResource that determines idleness by maintaining an internal
+ counter. When the counter is 0 - it is considered to be idle, when it is non-zero it is not
+ idle. This is very similar to the way a Semaphore behaves.
+
+ The counter may be incremented or decremented from any thread. If it reaches an illogical state
+ (like counter less than zero) it will throw an IllegalStateException.
+
+
+ This class can then be used to wrap up operations that while in progress should block tests from
+ accessing the UI.
+
the resource name this resource should report to Espresso.
+
+
+
debugCounting
+
if true increment & decrement calls will print trace information to logs.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Public Methods
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ void
+
+ decrement
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
Decrements the count of in-flight transactions to the resource being monitored.
+
+ If this operation results in the counter falling below 0 - an exception is raised.
Prints the current state of this resource to the logcat at info level.
+
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ String
+
+ getName
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
Returns the name of the resources (used for logging and idempotency of registration).
+
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ void
+
+ increment
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
Increments the count of in-flight transactions to the resource being monitored.
+
+ This method can be called from any thread.
+
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ boolean
+
+ isIdleNow
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
Returns true if resource is currently idle. Espresso will always call this
+ method from the main thread, therefore it should be non-blocking and return immediately.
+
with its implementation of IdlingResource.ResourceCallback so it can be notified asynchronously
+ that your resource is idle
+
from the main thread, but you are free to execute the callback's onTransitionToIdle from
+ any thread
+
once (when it is initially given a reference to your IdlingResource)
+
+
+ You only need to call this upon transition from busy to idle - if the resource is already idle
+ when the method is called invoking the call back is optional and has no significant impact.
+
Returns a matcher that verifies that the drawer is closed. Matches only when the drawer is
+ fully closed. Use isOpen() instead of not(isClosed())) when you wish to check
+ that the drawer is fully open.
+
Returns a matcher that verifies that the drawer is open. Matches only when the drawer is fully
+ open. Use isClosed() instead of not(isOpen()) when you wish to check that the
+ drawer is fully closed.
+
Most RecyclerViewActions are given a matcher to select a particular view / viewholder within
+ the RecyclerView. In this case the default behaviour is to expect that the matcher matches 1
+ and only one item within the RecyclerView.
+
+ This interface gives users the ability to override that type of behaviour and explicitly
+ select an item in the RecyclerView at a given position. This is similar to on the
+ onData(...).atPosition() api for AdapterViews.
+
ViewActions to interact RecyclerView. RecyclerView works differently than
+ AdapterView. In fact, RecyclerView is not an AdapterView anymore, hence it can't be used
+ in combination with onData(Matcher).
+
+
Returns a ViewAction which scrolls RecyclerView to the view matched by
+ itemViewMatcher.
+
+
+ This approach uses RecyclerView.ViewHolders to find the target view. It will create one ViewHolder
+ per item type and bind adapter data to the ViewHolder. If the itemViewMatcher matches a
+ ViewHolder the current position of the View is used to perform a
+ scrollToPosition(int).
+
Returns a ViewAction which scrolls RecyclerView to the view matched by
+ viewHolderMatcher.
+
+
+ This approach uses RecyclerView.ViewHolders to find the target view. It will create one ViewHolder
+ per item type and bind adapter data to the ViewHolder. If the itemViewMatcher matches a
+ ViewHolder the current position of the View is used to perform a
+ scrollToPosition(int). Note: scrollTo method is not overloaded, method
+ overloading with generic parameters is not possible.
+
A collection of Hamcrest matchers that matches a data row in a Cursor.
+
+
+ AdapterViews that are backed by a Cursor are very common. This class contains
+
+ Matchers that can be used together with
+ onData(Matcher) to match a data row in a
+ Cursor.
+ The
+ Matchers can only operate on a single data row of the cursor and Espresso
+ internally moves the Cursor to the correct adapter position.
+
Matches TextView elements having ellipsized text. If text is too long to fit into a TextView,
+ it can be either ellipsized ('Too long' shown as 'Too l…' or '… long') or cut off ('Too
+ long' shown as 'Too l'). Though acceptable in some cases, usually indicates bad user
+ experience.
+
+ Returns a matcher which accepts a view so long as a given percentage of that view's area is
+ not obscured by any other view and is thus visible to the user.
+
+
+
+
+ Returns a matcher that matches a descendant of Spinner that is displaying the string
+ of the selected item associated with the given resource id.
+
+
+
+
Returns an
+ Matcher that matches Views based on their siblings.
+
+ This may be particularly useful when a view cannot be uniquely selected on properties such as
+ text or R.id. For example: a call button is repeated several times in a contacts layout
+ and the only way to differentiate the call button view is by what appears next to it (e.g.
+ the unique name of the contact).
Returns a matcher that matches Views which are an instance of or subclass of the provided
+ class. Some versions of Hamcrest make the generic typing of this a nightmare, so we have a
+ special case for our users.
+
Returns a matcher which only accepts a view whose height and width fit perfectly within
+ the currently displayed region of this view.
+
+ There exist views (such as ScrollViews) whose height and width are larger then the physical
+ device screen by design. Such views will _never_ be completely displayed.
+
Returns a matcher that matches Views that are currently displayed on the screen to
+ the user.
+
+ Note: isDisplayed will select views that are partially displayed (eg: the full
+ height/width of the view is greater then the height/width of the visible rectangle).
+ If you wish to ensure the entire rectangle this view draws is displayed to the user use
+ isCompletelyDisplayed.
+
Returns a matcher which accepts a view so long as a given percentage of that view's area is
+ not obscured by any other view and is thus visible to the user.
+
+
Parameters
+
+
+
areaPercentage
+
an integer ranging from (0, 100] indicating how much percent of the
+ surface area of the view must be shown to the user to be accepted.
+
Returns a matcher that matches Views that have "effective" visibility set to the
+ given value. Effective visibility takes into account not only the view's visibility value,
+ but also that of its ancestors. In case of View.VISIBLE, this means that the view and all of
+ its ancestors have visibility=VISIBLE. In case of GONE and INVISIBLE, it's the opposite -
+ any GONE or INVISIBLE parent will make all of its children have their effective visibility.
+
+ Note: Contrary to what the name may imply, view visibility does not directly translate into
+ whether the view is displayed on screen (use isDisplayed() for that). For example,
+ the view and
+ all of its ancestors can have visibility=VISIBLE, but the view may need to be scrolled to in
+ order to be actually visible to the user. Unless you're specifically targeting the visibility
+ value with your test, use isDisplayed.
+
Returns a matcher that matches Views based on resource ids. Note: Android resource
+ ids are not guaranteed to be unique. You may have to pair this matcher with another one to
+ guarantee a unique view selection.
Same as withId(is(int)), but attempts to look up resource name of the given id and use an
+ R.id.myView style description with describeTo. If resource lookup is unavailable, at the time
+ describeTo is invoked, this will print out a simple "with id: %d". If resource lookup is
+ available, but looking up the name for the given id, fails, "with id: %d (resource name not
+ found)" will be returned as the description.
Returns a matcher that matches TextViews based on text property value. Note: View's
+ text property is never null. If you setText(null) it will still be "". Do not use null
+ matcher.
+ Provides base-level UI operations (such as injection of MotionEvents) that can be used to
+ build user actions such as clicks, scrolls, swipes, etc.
+
+
+
+
Indicates whether or not an Activity exists in our app within the "Visible Lifetime" state.
+
+
The "Visible Lifetime" is defined as an activity who's onStart() method has been called but
+ who's onStop() method has not been called.
+
+
During this time, the Activity may be visible to the user, and it may be receiving input
+ from the user. This time is a superset of the "Foreground lifetime' of the activity.
+
+
It may be the case that an application has activities in the "visible lifetime" but none in
+ the "Foreground lifetime." It may be the case that without user input an activity will shortly
+ transition into the "Foreground lifetime" in this state, however it also may not transition
+ without further user interaction.
+
+
Parameters
+
+
+
monitor
+
the ActivityLifecycleMonitor to use
+
+
+
+
+
Returns
+
true if any activity exists within it's foreground lifetime.
+
Utility methods for iterating over tree structured items.
+
+ Since the view hierarchy is a tree - having a method of iterating over its contents
+ is useful.
+
+ This is generalized for any object which can display tree like qualities - but this
+ generalization was done for testability concerns (since creating View hierarchies is a pain).
+
+ Only public methods of this utility class are considered public API of the test framework.
+
Returns an iterable which iterates thru the provided view and its children in a
+ breadth-first, row-level-order traversal. That is to say that for a view such as:
+ Root
+ / | \
+ A R U
+ /| |\
+ B D G N
+ Will be iterated: Root, A, R, U, B, D, G, N
Returns an iterable which iterates thru the provided view and its children in a
+ depth-first, in-order traversal. That is to say that for a view such as:
+ Root
+ / | \
+ A R U
+ /| |\
+ B D G N
+ Will be iterated: Root, A, B, D, R, G, N, U.
Creates an iterable that traverses the tree formed by the given root.
+
+ Along with iteration order, the distance from the root element is also tracked.
+
+
Parameters
+
+
+
root
+
the root view to track from.
+
+
+
+
+
Returns
+
An iterable of ViewAndDistance containing the view tree in a depth first order with
+ the distance of a given node from the root.
+
Aliases the current default Android JUnit 4 class runner, for future-proofing. If
+ future versions of JUnit change the default Runner class, they will also
+ change the definition of this class. Developers wanting to explicitly tag a
+ class as an Android JUnit 4 class should use @RunWith(AndroidJUnit4.class)
+
An Instrumentation that runs JUnit3 and JUnit4 tests against
+ an Android package (application).
+
+ Currently experimental. Based on InstrumentationTestRunner.
+
+ Will eventually support a superset of InstrumentationTestRunner features,
+ while maintaining command/output format compatibility with that class.
+
+
Typical Usage
+
+ Write JUnit3 style TestCases and/or JUnit4 style
+
+ Tests that perform tests against the classes in your package.
+ Make use of the InstrumentationRegistry if needed.
+
+ In an appropriate AndroidManifest.xml, define an instrumentation with android:name set to
+ AndroidJUnitRunner and the appropriate android:targetPackage
+ set.
+
+ Execution options:
+
+ Running all tests: adb shell am instrument -w
+ com.android.foo/android.support.test.runner.AndroidJUnitRunner
+
+ Running all tests in a class: adb shell am instrument -w
+ -e class com.android.foo.FooTest
+ com.android.foo/android.support.test.runner.AndroidJUnitRunner
+
+ Running a single test: adb shell am instrument -w
+ -e class com.android.foo.FooTest#testFoo
+ com.android.foo/android.support.test.runner.AndroidJUnitRunner
+
+ Running all tests in multiple classes: adb shell am instrument -w
+ -e class com.android.foo.FooTest,com.android.foo.TooTest
+ com.android.foo/android.support.test.runner.AndroidJUnitRunner
+
+ Running all tests listed in a file: adb shell am instrument -w
+ -e testFile /sdcard/tmp/testFile.txt com.android.foo/com.android.test.runner.AndroidJUnitRunner
+ The file should contain a list of line separated test classes and optionally methods (expected
+ format: com.android.foo.FooClassName#testMethodName).
+
+ Running all tests in a java package: adb shell am instrument -w
+ -e package com.android.foo.bar
+ com.android.foo/android.support.test.runner.AndroidJUnitRunner
+ To debug your tests, set a break point in your code and pass:
+ -e debug true
+
+ Running a specific test size i.e. annotated with
+ SmallTest or
+ MediumTest or
+ LargeTest:
+ adb shell am instrument -w -e size [small|medium|large]
+ com.android.foo/android.support.test.runner.AndroidJUnitRunner
+
+ Filter test run to tests with given annotation: adb shell am instrument -w
+ -e annotation com.android.foo.MyAnnotation
+ com.android.foo/android.support.test.runner.AndroidJUnitRunner
+
+ If used with other options, the resulting test run will contain the intersection of the two
+ options.
+ e.g. "-e size large -e annotation com.android.foo.MyAnnotation" will run only tests with both
+ the LargeTest and "com.android.foo.MyAnnotation" annotations.
+
+ Filter test run to tests without given annotation: adb shell am instrument -w
+ -e notAnnotation com.android.foo.MyAnnotation
+ com.android.foo/android.support.test.runner.AndroidJUnitRunner
+
+ As above, if used with other options, the resulting test run will contain the intersection of
+ the two options.
+ e.g. "-e size large -e notAnnotation com.android.foo.MyAnnotation" will run tests with
+ the LargeTest annotation that do NOT have the "com.android.foo.MyAnnotation" annotations.
+
+ Filter test run to tests without any of a list of annotations: adb shell am
+ instrument -w -e notAnnotation com.android.foo.MyAnnotation,com.android.foo.AnotherAnnotation
+ com.android.foo/android.support.test.runner.AndroidJUnitRunner
+
+ Filter test run to a shard of all tests, where numShards is an integer greater than 0 and
+ shardIndex is an integer between 0 (inclusive) and numShards (exclusive): adb shell am
+ instrument -w -e numShards 4 -e shardIndex 1
+ com.android.foo/android.support.test.runner.AndroidJUnitRunner
+
+ To run in 'log only' mode
+ -e log true
+ This option will load and iterate through all test classes and methods, but will bypass actual
+ test execution. Useful for quickly obtaining info on the tests to be executed by an
+ instrumentation command.
+
+ To generate EMMA code coverage:
+ -e coverage true
+ Note: this requires an emma instrumented build. By default, the code coverage results file
+ will be saved in a /data//coverage.ec file, unless overridden by coverageFile flag (see
+ below)
+
+ To specify EMMA code coverage results file path:
+ -e coverageFile /sdcard/myFile.ec
+
+ To specify one or more
+
+ RunListeners to observe the test run:
+ -e listener com.foo.Listener,com.foo.Listener2
+
+ OR, specify the multiple listeners in the AndroidManifest via a meta-data tag:
+ instrumentation android:name="android.support.test.runner.AndroidJUnitRunner" ...
+ meta-data android:name="listener"
+ android:value="com.foo.Listener,com.foo.Listener2"
+
+ Set timeout (in milliseconds) that will be applied to each test:
+ -e timeout_msec 5000
+
+ Supported for both JUnit3 and JUnit4 style tests. For JUnit3 tests, this flag is the only way
+ to specify timeouts. For JUnit4 tests, this flag overrides timeouts specified via
+
+ org.junit.rules.Timeout. Please note that in JUnit4
+
+ org.junit.Test#timeout()
+ annotation take precedence over both, this flag and
+
+ org.junit.Test#timeout()
+ annotation.
+
+ To disable Google Analytics:
+ -e disableAnalytics true
+
+
+
+
+
+
+
Ensures all activities launched in this instrumentation are finished before the
+ instrumentation exits.
+
+ Subclasses who override this method should do their finish processing and then call
+ super.finish to invoke this logic. Not waiting for all activities to finish() before exiting
+ can cause device wide instability.
+
Sets up lifecycle monitoring, and argument registry.
+
+ Subclasses must call up to onCreate(). This onCreate method does not call start()
+ it is the subclasses responsibility to call start if it desires.
+
+ An Instrumentation that runs JUnit3 and JUnit4 tests against
+ an Android package (application).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Class Overview
+
An instrumentation that enables several advanced features and makes some hard guarantees about
+ the state of the application under instrumentation.
+
+ A short list of these capabilities:
+
+
Forces Application.onCreate() to happen before Instrumentation.onStart() runs (ensuring your
+ code always runs in a sane state).
+
Logs application death due to exceptions.
+
Allows tracking of activity lifecycle states.
+
Registers instrumentation arguments in an easy to access place.
+
Ensures your activities are creating themselves in reasonable amounts of time.
+
Provides facilities to dump current app threads to test outputs.
+
Ensures all activities finish before instrumentation exits.
+
+
+ This Instrumentation is *NOT* a test instrumentation (some of its subclasses are). It makes no
+ assumptions about what the subclass wants to do.
+
+
+
+
+
+
+
Ensures all activities launched in this instrumentation are finished before the
+ instrumentation exits.
+
+ Subclasses who override this method should do their finish processing and then call
+ super.finish to invoke this logic. Not waiting for all activities to finish() before exiting
+ can cause device wide instability.
+
Sets up lifecycle monitoring, and argument registry.
+
+ Subclasses must call up to onCreate(). This onCreate method does not call start()
+ it is the subclasses responsibility to call start if it desires.
+
Ensures we've onStopped() all activities which were onStarted().
+
+ According to Activity's contract, the process is not killable between onStart and onStop.
+ Breaking this contract (which finish() will if you let it) can cause bad behaviour (including
+ a full restart of system_server).
+
+
+ We give the app 2 seconds to stop all its activities, then we proceed.
+
Callback for monitoring activity lifecycle events. These callbacks are invoked on the main
+ thread, so any long operations or violating the strict mode policies should be avoided.
+
Interface for tests to use when they need to query the activity lifecycle state.
+
+ Activity lifecycle changes occur only on the UI thread - therefore listeners registered with
+ an ActivityLifecycleMonitor should expect to be invoked on the UI thread. The direct query
+ methods can only be called on the UI thread because otherwise they would not be able to return
+ consistent responses.
+
+
+ Retrieve instances of the monitor thru ActivityLifecycleMonitorRegistry.
+
+
+ Detecting these lifecycle states requires support from Instrumentation, therefore do not expect
+ an instance to be present under any arbitrary instrumentation.
+
Adds a new callback that will be notified when lifecycle changes occur.
+
+ Implementors will not hold a strong ref to the callback, the code which registers callbacks
+ is responsible for this. Code which registers callbacks should responsibly
+ remove their callback when it is no longer needed.
+
+
+ Callbacks are executed on the main thread of the application, and should take care not to
+ block or otherwise perform expensive operations as it will directly impact the application.
+
Returns all activities in a given stage of their lifecycle.
+
+ This method can only return a consistant and correct answer from the main thread, therefore
+ callers should always invoke it from the main thread and implementors are free to throw an
+ exception if the call is not made on the main thread.
+
+
+ Implementors should ensure this method returns a consistant response if called from a
+ lifecycle callback also registered with this monitor (eg: it would be horriblely wrong if a
+ callback sees PAUSED and calls this method with the PAUSED and does not see its activity in
+ the response.
+
+
+ Callers should be aware that the monitor implementation may not hold strong references to the
+ Activities in the application. Therefore stages which are considered end stages or eligible
+ for garbage collection on low memory situations may not return an instance of a particular
+ activity if it has been garbage collected.
+
+
Parameters
+
+
+
stage
+
the stage to query for.
+
+
+
+
+
Returns
+
a snapshot Collection of activities in the given stage. This collection may be empty.
Returns the current lifecycle stage of a given activity.
+
+ This method can only return a consistant and correct answer
+ from the main thread, therefore callers should always invoke
+ it from the main thread and implementors are free to throw an
+ exception if the call is not made on the main thread.
+
+
+ Implementors should ensure this method returns a consistant response if called from a
+ lifecycle callback also registered with this monitor (eg: it would be horriblely wrong if a
+ callback sees PAUSED and calls this method with the same activity and gets RESUMED.
+
+ An instrumentation that enables several advanced features and makes some hard guarantees about
+ the state of the application under instrumentation.
+
+
+
+
By is a utility class which enables the creation of BySelectors in a concise
+ manner.
+
+
Its primary function is to provide static factory methods for constructing BySelectors
+ using a shortened syntax. For example, you would use findObject(By.text("foo")) rather
+ than findObject(new BySelector().text("foo")) to select UI elements with the text value
+ "foo".
Sets the class name criteria for matching. A UI element will be considered a match if its
+ full class name matches the classNamePattern and all other criteria for this
+ selector are met.
Sets the class name criteria for matching. A UI element will be considered a match if its
+ class name exactly matches the className parameter and all other criteria for
+ this selector are met. If className starts with a period, it is assumed to be in the
+ android.widget package.
Sets the class name criteria for matching. A UI element will be considered a match if its
+ class name matches clazz and all other criteria for this selector are met.
Sets the class name criteria for matching. A UI element will be considered a match if its
+ package and class name exactly match the packageName and className parameters
+ and all other criteria for this selector are met.
Sets the content description criteria for matching. A UI element will be considered a match
+ if its content description matches the contentDescriptionPattern and all
+ other criteria for this selector are met.
Sets the content description criteria for matching. A UI element will be considered a match
+ if its content description exactly matches the contentDescription parameter and all
+ other criteria for this selector are met.
Sets the content description criteria for matching. A UI element will be considered a match
+ if its content description contains the substring parameter and all other criteria
+ for this selector are met.
Sets the content description criteria for matching. A UI element will be considered a match
+ if its content description ends with the substring parameter and all other criteria
+ for this selector are met.
Sets the content description criteria for matching. A UI element will be considered a match
+ if its content description starts with the substring parameter and all other criteria
+ for this selector are met.
Adds a child selector criteria for matching. A UI element will be considered a match if it
+ has a child element (direct descendant) which matches the childSelector and all
+ other criteria for this selector are met. If specified more than once, matches must be found
+ for all childSelectors.
+
+
Parameters
+
+
+
childSelector
+
The selector used to find a matching child element.
+
+ public
+
+
+
+
+ BySelector
+
+ hasDescendant
+ (BySelector descendantSelector, int maxDepth)
+
+
+
+
+
+
+
+
+
+
+
+
+
Adds a descendant selector criteria for matching. A UI element will be considered a match if
+ it has a descendant element which matches the descendantSelector and all other
+ criteria for this selector are met. If specified more than once, matches must be found for
+ all descendantSelectors.
+
+
Parameters
+
+
+
descendantSelector
+
The selector used to find a matching descendant element.
+
+
+
maxDepth
+
The maximum depth under the element to search the descendant.
Adds a descendant selector criteria for matching. A UI element will be considered a match if
+ it has a descendant element which matches the descendantSelector and all other
+ criteria for this selector are met. If specified more than once, matches must be found for
+ all descendantSelectors.
+
+
Parameters
+
+
+
descendantSelector
+
The selector used to find a matching descendant element.
Sets the application package name criteria for matching. A UI element will be considered a
+ match if its application package name exactly matches the applicationPackage
+ parameter and all other criteria for this selector are met.
Sets the package name criteria for matching. A UI element will be considered a match if its
+ application package name matches the applicationPackagePattern and all other
+ criteria for this selector are met.
+
+ public
+
+
+
+
+ BySelector
+
+ res
+ (String resourceName)
+
+
+
+
+
+
+
+
+
+
+
+
+
Sets the resource name criteria for matching. A UI element will be considered a match if its
+ resource name exactly matches the resourceName parameter and all other criteria for
+ this selector are met.
+
+ public
+
+
+
+
+ BySelector
+
+ res
+ (Pattern resourceName)
+
+
+
+
+
+
+
+
+
+
+
+
+
Sets the resource name criteria for matching. A UI element will be considered a match if its
+ resource name matches the resourceNamePattern and all other criteria for
+ this selector are met.
+
+ public
+
+
+
+
+ BySelector
+
+ res
+ (String resourcePackage, String resourceId)
+
+
+
+
+
+
+
+
+
+
+
+
+
Sets the resource name criteria for matching. A UI element will be considered a match if its
+ resource package and resource id exactly match the resourcePackage and
+ resourceId parameters and all other criteria for this selector are met.
+
+ public
+
+
+
+
+ BySelector
+
+ text
+ (Pattern textValue)
+
+
+
+
+
+
+
+
+
+
+
+
+
Sets the text value criteria for matching. A UI element will be considered a match if its
+ text value matches the textValuePattern and all other criteria for this
+ selector are met.
+
+ public
+
+
+
+
+ BySelector
+
+ text
+ (String textValue)
+
+
+
+
+
+
+
+
+
+
+
+
+
Sets the text value criteria for matching. A UI element will be considered a match if its
+ text value exactly matches the textValue parameter and all other criteria for this
+ selector are met.
Sets the text value criteria for matching. A UI element will be considered a match if its
+ text value contains the substring parameter and all other criteria for this selector
+ are met.
Sets the text value criteria for matching. A UI element will be considered a match if its
+ text value ends with the substring parameter and all other criteria for this selector
+ are met.
Sets the text value criteria for matching. A UI element will be considered a match if its
+ text value starts with the substring parameter and all other criteria for this
+ selector are met.
Returns a String representation of this BySelector. The format is
+ "BySelector [<KEY>='<VALUE> ... ]". Each criteria is listed as a key-value pair
+ where the key is the name of the criteria expressed in all caps (e.g. CLAZZ, RES, etc).
+
Allows you to set key parameters for running uiautomator tests. The new
+ settings take effect immediately and can be changed any time during a test run.
+
+ To modify parameters using Configurator, first obtain an instance by calling
+ getInstance(). As a best practice, make sure you always save
+ the original value of any parameter that you are modifying. After running your
+ tests with the modified parameters, make sure to also restore
+ the original parameter values, otherwise this will impact other tests cases.
+
+ public
+
+
+
+
+ long
+
+ getActionAcknowledgmentTimeout
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
Gets the current timeout for waiting for an acknowledgment of generic
+ uiautomator actions, such as clicks, text setting, and menu presses.
+
+ The acknowledgment is an AccessibilityEvent,
+ corresponding to an action, that lets the framework determine if the
+ action was successful. Generally, this timeout should not be modified.
+ See UiObject
+
+ public
+
+
+
+
+ long
+
+ getKeyInjectionDelay
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
Gets the current delay between key presses when injecting text input.
+ See setText(String)
+
+
Returns
+
current delay in milliseconds
+
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ long
+
+ getScrollAcknowledgmentTimeout
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
Gets the timeout for waiting for an acknowledgement of an
+ uiautomtor scroll swipe action.
+
+ The acknowledgment is an AccessibilityEvent,
+ corresponding to the scroll action, that lets the framework determine if
+ the scroll action was successful. Generally, this timeout should not be modified.
+ See UiScrollable
+
+
Returns
+
current timeout in milliseconds
+
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ long
+
+ getWaitForIdleTimeout
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
Gets the current timeout used for waiting for the user interface to go
+ into an idle state.
+
+ By default, all core uiautomator objects except UiDevice will perform
+ this wait before starting to search for the widget specified by the
+ object's UiSelector. Once the idle state is detected or the
+ timeout elapses (whichever occurs first), the object will start to wait
+ for the selector to find a match.
+ See setWaitForSelectorTimeout(long)
+
+
Returns
+
Current timeout value in milliseconds
+
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ long
+
+ getWaitForSelectorTimeout
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
Gets the current timeout for waiting for a widget to become visible in
+ the user interface so that it can be matched by a selector.
+
+ Because user interface content is dynamic, sometimes a widget may not
+ be visible immediately and won't be detected by a selector. This timeout
+ allows the uiautomator framework to wait for a match to be found, up until
+ the timeout elapses.
Sets the timeout for waiting for an acknowledgment of generic uiautomator
+ actions, such as clicks, text setting, and menu presses.
+
+ The acknowledgment is an AccessibilityEvent,
+ corresponding to an action, that lets the framework determine if the
+ action was successful. Generally, this timeout should not be modified.
+ See UiObject
Sets the timeout for waiting for an acknowledgement of an
+ uiautomtor scroll swipe action.
+
+ The acknowledgment is an AccessibilityEvent,
+ corresponding to the scroll action, that lets the framework determine if
+ the scroll action was successful. Generally, this timeout should not be modified.
+ See UiScrollable
Sets the timeout for waiting for the user interface to go into an idle
+ state before starting a uiautomator action.
+
+ By default, all core uiautomator objects except UiDevice will perform
+ this wait before starting to search for the widget specified by the
+ object's UiSelector. Once the idle state is detected or the
+ timeout elapses (whichever occurs first), the object will start to wait
+ for the selector to find a match.
+ See setWaitForSelectorTimeout(long)
Sets the timeout for waiting for a widget to become visible in the user
+ interface so that it can be matched by a selector.
+
+ Because user interface content is dynamic, sometimes a widget may not
+ be visible immediately and won't be detected by a selector. This timeout
+ allows the uiautomator framework to wait for a match to be found, up until
+ the timeout elapses.
Perform initialization specific to UiAutomator test. It sets up the test case so that
+ it can access the UiDevice and gives it access to the command line arguments.
+ This class is deprecated.
+ It is no longer necessary to extend UiAutomatorTestCase. You can use
+ getInstance(Instrumentation) from any test class as long as you have access to
+ an Instrumentation instance.
+
+
+
+
Class Overview
+
UI Automator test case that is executed on the device.
Provides support for running tests to report interim status
+
+
Returns
+
IAutomationSupport
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+ Performs a two-pointer gesture, where each pointer moves diagonally
+ opposite across the other, from the center out towards the edges of the
+ this UiObject.
+
+
+
+
Searches for child UI element within the constraints of this UiCollection 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
+
+
+
childPattern
+
UiSelector selector of the child pattern to match and return
+
+
+
text
+
String of the identifying child contents of of the childPattern
+
+ public
+
+
+
+
+ UiObject
+
+ getChildByInstance
+ (UiSelector childPattern, int instance)
+
+
+
+
+
+
+
+
+
+
+
+
+
Searches for child UI element within the constraints of this UiCollection UiSelector
+ selector.
+
+ 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
+
+
+
childPattern
+
UiSelector selector of the child pattern to match and return
+
+
+
instance
+
int the desired matched instance of this childPattern
Searches for child UI element within the constraints of this UiCollection UiSelector
+ selector.
+
+ It looks for any child matching the childPattern argument that has
+ a child 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 identifying child element that matched the
+ text attribute.
+
+
Parameters
+
+
+
childPattern
+
UiSelector selector of the child pattern to match and return
+
+
+
text
+
String of the identifying child contents of of the childPattern
+
+ 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
+
+
+
childPattern
+
a UiSelector that represents the matching child UI
+ elements to count
+
+
+
+
+
Returns
+
the number of matched childPattern under the current UiCollection
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.
+
+ This method is deprecated.
+ Should use getInstance(Instrumentation) instead. This version hides
+ UiDevice's dependency on having an Instrumentation reference and is prone to misuse.
+
+
+
+
+ Take a screenshot of current window and store it as PNG
+
+ Default scale of 1.0f (original size) and 90% quality is used
+ The screenshot is adjusted per screen rotation
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ boolean
+
+
+ takeScreenshot(File storePath, float scale, int quality)
+
+
+ Take a screenshot of current window and store it as PNG
+
+ The screenshot is adjusted per screen rotation
+
+
+
+
+
+ public
+
+
+
+
+ boolean
+
+ click
+ (int x, int y)
+
+
+
+
+
+
+
+
+
+
+
+
+
Perform a click at arbitrary coordinates specified by the user
+
+
Parameters
+
+
+
x
+
coordinate
+
+
+
y
+
coordinate
+
+
+
+
+
Returns
+
true if the click succeeded else false
+
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ boolean
+
+ drag
+ (int startX, int startY, int endX, int endY, int steps)
+
+
+
+
+
+
+
+
+
+
+
+
+
Performs a swipe from one coordinate to another coordinate. You can control
+ the smoothness and speed of the swipe by specifying the number of steps.
+ Each step execution is throttled to 5 milliseconds per step, so for a 100
+ steps, the swipe will take around 0.5 seconds to complete.
+
+
Parameters
+
+
+
startX
+
X-axis value for the starting coordinate
+
+
+
startY
+
Y-axis value for the starting coordinate
+
+
+
endX
+
X-axis value for the ending coordinate
+
+
+
endY
+
Y-axis value for the ending coordinate
+
+
+
steps
+
is the number of steps for the swipe action
+
+
+
+
+
Returns
+
true if swipe is performed, false if the operation fails
+ or the coordinates are invalid
Helper method used for debugging to dump the current window's layout hierarchy.
+ Relative file paths are stored the application's internal private storage location.
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
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ Point
+
+ getDisplaySizeDp
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
Returns the display size in dp (device-independent pixel)
+
+ The returned display size is adjusted per screen rotation. Also this will return the actual
+ size of the screen, rather than adjusted per system decorations (like status bar).
+
+
Returns
+
a Point containing the display size in dp
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+ This method is deprecated.
+ Should use getInstance(Instrumentation) instead. This version hides
+ UiDevice's dependency on having an Instrumentation reference and is prone to misuse.
+
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
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.
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.
Enables or disables layout hierarchy compression.
+
+ If compression is enabled, the layout hierarchy derived from the Acessibility
+ framework will only contain nodes that are important for uiautomator
+ testing. Any unnecessary surrounding layout nodes that make viewing
+ and searching the hierarchy inefficient are removed.
+
+
Parameters
+
+
+
compressed
+
true to enable compression; else, false to disable
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().
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().
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
+
+
+
segments
+
is Point array containing at least one Point object
+
+
+
segmentSteps
+
steps to inject between two Points
+
+
+
+
+
Returns
+
true on success
+
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ boolean
+
+ swipe
+ (int startX, int startY, int endX, int endY, int steps)
+
+
+
+
+
+
+
+
+
+
+
+
+
Performs a swipe from one coordinate to another using the number of steps
+ to determine smoothness and speed. Each step execution is throttled to 5ms
+ per step. So for a 100 steps, the swipe will take about 1/2 second to complete.
+
+
Parameters
+
+
+
steps
+
is the number of move steps sent to the system
+
+
+
+
+
Returns
+
false if the operation fails or the coordinates are invalid
Take a screenshot of current window and store it as PNG
+
+ Default scale of 1.0f (original size) and 90% quality is used
+ The screenshot is adjusted per screen rotation
+
+
Parameters
+
+
+
storePath
+
where the PNG should be written to
+
+
+
+
+
Returns
+
true if screen shot is created successfully, false otherwise
+
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ boolean
+
+ takeScreenshot
+ (File storePath, float scale, int quality)
+
+
+
+
+
+
+
+
+
+
+
+
+
Take a screenshot of current window and store it as PNG
+
+ The screenshot is adjusted per screen rotation
+
+
Parameters
+
+
+
storePath
+
where the PNG should be written to
+
+
+
scale
+
scale the screenshot down if needed; 1.0f for original size
+
+
+
quality
+
quality of the PNG compression; range: 0-100
+
+
+
+
+
Returns
+
true if screen shot is created successfully, false otherwise
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
+
+
+
+
+ R
+
+ wait
+ (SearchCondition<R> condition, long timeout)
+
Waits for the current application to idle.
+ Default wait timeout is 10 seconds
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ boolean
+
+ waitForWindowUpdate
+ (String packageName, long timeout)
+
+
+
+
+
+
+
+
+
+
+
+
+
Waits for a window content update event to occur.
+
+ If a package name for the window is specified, but the current window
+ does not have the same package name, the function returns immediately.
+
+
Parameters
+
+
+
packageName
+
the specified window package name (can be null).
+ If null, a window update from any front-end window will end the wait
+
+
+
timeout
+
the timeout for the wait
+
+
+
+
+
Returns
+
true if a window update occurred, false if timeout has elapsed or if the current
+ window does not have the specified package name
+
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ void
+
+ wakeUp
+ ()
+
+
+
+
+
+
+
+
+
+
+
+
+
This method simulates pressing the power button if the screen is OFF else
+ it does nothing if the screen is already ON.
+
+ If the screen was OFF and it just got turned ON, this method will insert a 500ms delay
+ to allow the device time to wake up and accept input.
+ UiScrollable is a UiCollection and provides support for searching
+ for items in scrollable layout elements.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
Class Overview
+
A UiObject is a representation of a view. It is not in any way directly bound to a
+ view as an object reference. A UiObject contains information to help it
+ locate a matching view at runtime based on the UiSelector properties specified in
+ its constructor. Once you create an instance of a UiObject, it can
+ be reused for different views that match the selector criteria.
+
+ This constructor is deprecated.
+ Use findObject(UiSelector) instead. This version hides
+ UiObject's dependency on UiDevice and is prone to misuse.
+
+
+
+
+ Performs a two-pointer gesture, where each pointer moves diagonally
+ opposite across the other, from the center out towards the edges of the
+ this UiObject.
+
+
+
+
+ This constructor is deprecated.
+ Use findObject(UiSelector) instead. This version hides
+ UiObject's dependency on UiDevice and is prone to misuse.
+
+
Constructs a UiObject to represent a view that matches the specified
+ selector criteria.
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 sets focus on the editable field, selects all of its
+ existing content, and clears it by sending a DELETE key press
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
+
+
+
timeout
+
timeout before giving up on waiting for a new window
+
+ public
+
+
+
+
+ boolean
+
+ dragTo
+ (UiObject destObj, int steps)
+
+
+
+
+
+
+
+
+
+
+
+
+
Drags this object to a destination UiObject.
+ The number of steps specified in your input parameter can influence the
+ drag speed, and varying speeds may impact the results. Consider
+ evaluating different speeds when using this method in your tests.
+
+
Parameters
+
+
+
destObj
+
the destination UiObject.
+
+
+
steps
+
usually 40 steps. You can increase or decrease the steps to change the speed.
+
+ public
+
+
+
+
+ boolean
+
+ dragTo
+ (int destX, int destY, int steps)
+
+
+
+
+
+
+
+
+
+
+
+
+
Drags this object to arbitrary coordinates.
+ The number of steps specified in your input parameter can influence the
+ drag speed, and varying speeds may impact the results. Consider
+ evaluating different speeds when using this method in your tests.
+
+
Parameters
+
+
+
destX
+
the X-axis coordinate.
+
+
+
destY
+
the Y-axis coordinate.
+
+
+
steps
+
usually 40 steps. You can increase or decrease the steps to change the speed.
Check if view exists.
+
+ This methods performs a waitForExists(long) with zero timeout. This
+ basically returns immediately whether the view represented by this UiObject
+ exists or not. If you need to wait longer for this view, then see
+ waitForExists(long).
+
+
Returns
+
true if the view represented by this UiObject does exist
Performs a multi-touch gesture. You must specify touch coordinates for
+ at least 2 pointers. Each pointer must have all of its touch steps
+ defined in an array of MotionEvent.PointerCoords. You can use this method to
+ specify complex gestures, like circles and irregular shapes, where each
+ pointer may take a different path.
+
+ To create a single point on a pointer's touch path:
+
+ PointerCoords p = new PointerCoords();
+ p.x = stepX;
+ p.y = stepY;
+ p.pressure = 1;
+ p.size = 1;
+
+
+
Parameters
+
+
+
touches
+
represents the pointers' paths. Each MotionEvent.PointerCoords
+ array represents a different pointer. Each MotionEvent.PointerCoords in an
+ array element represents a touch point on a pointer's path.
+
+
+
+
+
Returns
+
true if all touch events for this gesture are injected successfully,
+ false otherwise
+
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ boolean
+
+ performTwoPointerGesture
+ (Point startPoint1, Point startPoint2, Point endPoint1, Point endPoint2, int steps)
+
+
+
+
+
+
+
+
+
+
+
+
+
Generates a two-pointer gesture with arbitrary starting and ending points.
+
+
Parameters
+
+
+
startPoint1
+
start point of pointer 1
+
+
+
startPoint2
+
start point of pointer 2
+
+
+
endPoint1
+
end point of pointer 1
+
+
+
endPoint2
+
end point of pointer 2
+
+
+
steps
+
the number of steps for the gesture. Steps are injected
+ about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete.
+
+
+
+
+
Returns
+
true if all touch events for this gesture are injected successfully,
+ false otherwise
+
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ boolean
+
+ pinchIn
+ (int percent, int steps)
+
+
+
+
+
+
+
+
+
+
+
+
+
Performs a two-pointer gesture, where each pointer moves diagonally
+ toward the other, from the edges to the center of this UiObject .
+
+
Parameters
+
+
+
percent
+
percentage of the object's diagonal length for the pinch gesture
+
+
+
steps
+
the number of steps for the gesture. Steps are injected
+ about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete.
+
+
+
+
+
Returns
+
true if all touch events for this gesture are injected successfully,
+ false otherwise
+
+ public
+
+
+
+
+ boolean
+
+ pinchOut
+ (int percent, int steps)
+
+
+
+
+
+
+
+
+
+
+
+
+
Performs a two-pointer gesture, where each pointer moves diagonally
+ opposite across the other, from the center out towards the edges of the
+ this UiObject.
+
+
Parameters
+
+
+
percent
+
percentage of the object's diagonal length for the pinch gesture
+
+
+
steps
+
the number of steps for the gesture. Steps are injected
+ about 5 milliseconds apart, so 100 steps may take around 0.5 seconds to complete.
+
+
+
+
+
Returns
+
true if all touch events for this gesture are injected successfully,
+ false otherwise
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 sets focus on the editable field, clears its existing
+ content, then 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.
+
+
Improvements:
+ Post API Level 19 (KitKat release), the underlying implementation is updated to a dedicated
+ set text accessibility action, and it also now supports Unicode.
Performs the swipe down action on the UiObject.
+ The swipe gesture can be performed over any surface. The targeted
+ UI element does not need to be scrollable.
+ See also:
+
indicates 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.
Performs the swipe left action on the UiObject.
+ The swipe gesture can be performed over any surface. The targeted
+ UI element does not need to be scrollable.
+ See also:
+
indicates 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.
Performs the swipe right action on the UiObject.
+ The swipe gesture can be performed over any surface. The targeted
+ UI element does not need to be scrollable.
+ See also:
+
indicates 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.
indicates 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.
Waits a specified length of time for a view to become visible.
+
+ This method waits until the view 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
+
+
+
timeout
+
the amount of time to wait (in milliseconds)
+
+
+
+
+
Returns
+
true if the view is displayed, else false if timeout elapsed while waiting
Waits a specified length of time for a view to become undetectable.
+
+ This method waits until a view is no longer matchable, or until the
+ timeout has elapsed.
+
+ A view 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
+
+
+
timeout
+
time 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.
A UiObject2 represents a UI element. Unlike UiObject, it is bound to a particular
+ view instance and can become stale if the underlying view object is destroyed. As a result, it
+ may be necessary to call findObject(BySelector) to obtain a new
+ UiObject2 instance if the UI changes significantly.
+
UiScrollable is a UiCollection and provides support for searching
+ for items in scrollable layout elements. This class can be used with
+ horizontally or vertically scrollable controls.
+ Performs a forward scroll action on the scrollable layout element until
+ the content-description is found, or until swipe attempts have been exhausted.
+
+
+
+
+ Performs a forward scroll action on the scrollable layout element until
+ the text you provided is visible, or until swipe attempts have been exhausted.
+
+
+
+
+ Performs a two-pointer gesture, where each pointer moves diagonally
+ opposite across the other, from the center out towards the edges of the
+ this UiObject.
+
+
+
+
Performs a backwards fling action with the default number of fling
+ steps (5). If the swipe direction is set to vertical,
+ then the swipe will be performed from top to bottom. If the swipe
+ direction is set to horizontal, then the swipes will be performed from
+ left to right. Make sure to take into account devices configured with
+ right-to-left languages like Arabic and Hebrew.
+
+
Returns
+
true if scrolled, and false if can't scroll anymore
Performs a forward fling with the default number of fling steps (5).
+ If the swipe direction is set to vertical, then the swipes will be
+ performed from bottom to top. If the swipe
+ direction is set to horizontal, then the swipes will be performed from
+ right to left. Make sure to take into account devices configured with
+ right-to-left languages like Arabic and Hebrew.
Performs a fling gesture to reach the beginning of a scrollable layout element.
+ The beginning can be at the top-most edge in the case of vertical controls, or
+ the left-most edge for horizontal controls. Make sure to take into
+ account devices configured with right-to-left languages like Arabic and Hebrew.
Performs a fling gesture to reach the end of a scrollable layout element.
+ The end can be at the bottom-most edge in the case of vertical controls, or
+ the right-most edge for horizontal controls. Make sure to take into
+ account devices configured with right-to-left languages like Arabic and Hebrew.
Searches for a child element in the present scrollable container.
+ The search first looks for a child element that matches the selector
+ you provided, then looks for the content-description in its children elements.
+ If both search conditions are fulfilled, the method returns a {@ link UiObject}
+ representing the element matching the selector (not the child element in its
+ subhierarchy containing the content-description). By default, this method performs a
+ scroll search.
+ See getChildByDescription(UiSelector, String, boolean)
+
+
Parameters
+
+
+
childPattern
+
UiSelector for a child in a scollable layout element
+
+
+
text
+
Content-description to find in the children of
+ the childPattern match
+
+
+
+
+
Returns
+
UiObject representing the child element that matches the search conditions
Searches for a child element in the present scrollable container.
+ The search first looks for a child element that matches the selector
+ you provided, then looks for the content-description in its children elements.
+ If both search conditions are fulfilled, the method returns a {@ link UiObject}
+ representing the element matching the selector (not the child element in its
+ subhierarchy containing the content-description).
+
+
Parameters
+
+
+
childPattern
+
UiSelector for a child in a scollable layout element
+
+
+
text
+
Content-description to find in the children of
+ the childPattern match (may be a partial match)
+
+
+
allowScrollSearch
+
set to true if scrolling is allowed
+
+
+
+
+
Returns
+
UiObject representing the child element that matches the search conditions
+
+ public
+
+
+
+
+ UiObject
+
+ getChildByInstance
+ (UiSelector childPattern, int instance)
+
+
+
+
+
+
+
+
+
+
+
+
+
Searches for a child element in the present scrollable container that
+ matches the selector you provided. The search is performed without
+ scrolling and only on visible elements.
+
+
Parameters
+
+
+
childPattern
+
UiSelector for a child in a scollable layout element
+
+
+
instance
+
int number representing the occurance of
+ a childPattern match
+
+
+
+
+
Returns
+
UiObject representing the child element that matches the search conditions
Searches for a child element in the present scrollable
+ container. The search first looks for a child element that matches the
+ selector you provided, then looks for the text in its children elements.
+ If both search conditions are fulfilled, the method returns a {@ link UiObject}
+ representing the element matching the selector (not the child element in its
+ subhierarchy containing the text). By default, this method performs a
+ scroll search.
+ See getChildByText(UiSelector, String, boolean)
+
+
Parameters
+
+
+
childPattern
+
UiSelector selector for a child in a scrollable layout element
+
+
+
text
+
String to find in the children of the childPattern match
+
+
+
+
+
Returns
+
UiObject representing the child element that matches the search conditions
Searches for a child element in the present scrollable container. The
+ search first looks for a child element that matches the
+ selector you provided, then looks for the text in its children elements.
+ If both search conditions are fulfilled, the method returns a {@ link UiObject}
+ representing the element matching the selector (not the child element in its
+ subhierarchy containing the text).
+
+
Parameters
+
+
+
childPattern
+
UiSelector selector for a child in a scrollable layout element
+
+
+
text
+
String to find in the children of the childPattern match
+
+
+
allowScrollSearch
+
set to true if scrolling is allowed
+
+
+
+
+
Returns
+
UiObject representing the child element that matches the search conditions
Returns the percentage of a widget's size that's considered as a no-touch
+ zone when swiping. The no-touch zone is set as a 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.
Performs a backward scroll. If the swipe direction is set to vertical,
+ then the swipes will be performed from top to bottom. If the swipe
+ direction is set to horizontal, then the swipes will be performed from
+ left to right. Make sure to take into account devices configured with
+ right-to-left languages like Arabic and Hebrew.
+
+
Parameters
+
+
+
steps
+
number of steps. Use this to control the speed of the scroll action.
Performs a backward scroll with the default number of scroll steps (55).
+ If the swipe direction is set to vertical,
+ then the swipes will be performed from top to bottom. If the swipe
+ direction is set to horizontal, then the swipes will be performed from
+ left to right. Make sure to take into account devices configured with
+ right-to-left languages like Arabic and Hebrew.
+
+
Returns
+
true if scrolled, and false if can't scroll anymore
Performs a forward scroll action on the scrollable layout element until
+ the content-description is found, or until swipe attempts have been exhausted.
+ See setMaxSearchSwipes(int)
+
+
Parameters
+
+
+
text
+
content-description to find within the contents of this scrollable layout element.
Performs a forward scroll with the default number of scroll steps (55).
+ If the swipe direction is set to vertical,
+ then the swipes will be performed from bottom to top. If the swipe
+ direction is set to horizontal, then the swipes will be performed from
+ right to left. Make sure to take into account devices configured with
+ right-to-left languages like Arabic and Hebrew.
Performs a forward scroll. If the swipe direction is set to vertical,
+ then the swipes will be performed from bottom to top. If the swipe
+ direction is set to horizontal, then the swipes will be performed from
+ right to left. Make sure to take into account devices configured with
+ right-to-left languages like Arabic and Hebrew.
+
+
Parameters
+
+
+
steps
+
number of steps. Use this to control the speed of the scroll action
Performs a forward scroll action on the scrollable layout element until
+ the text you provided is visible, or until swipe attempts have been exhausted.
+ See setMaxSearchSwipes(int)
Scrolls to the beginning of a scrollable layout element. The beginning
+ can be at the top-most edge in the case of vertical controls, or the
+ left-most edge for horizontal controls. Make sure to take into account
+ devices configured with right-to-left languages like Arabic and Hebrew.
+
+ public
+
+
+
+
+ boolean
+
+ scrollToBeginning
+ (int maxSwipes, int steps)
+
+
+
+
+
+
+
+
+
+
+
+
+
Scrolls to the beginning of a scrollable layout element. The beginning
+ can be at the top-most edge in the case of vertical controls, or the
+ left-most edge for horizontal controls. Make sure to take into account
+ devices configured with right-to-left languages like Arabic and Hebrew.
+
+
Parameters
+
+
+
steps
+
use steps to control the speed, so that it may be a scroll, or fling
+
+ public
+
+
+
+
+ boolean
+
+ scrollToEnd
+ (int maxSwipes, int steps)
+
+
+
+
+
+
+
+
+
+
+
+
+
Scrolls to the end of a scrollable layout element. The end can be at the
+ bottom-most edge in the case of vertical controls, or the right-most edge for
+ horizontal controls. Make sure to take into account devices configured with
+ right-to-left languages like Arabic and Hebrew.
+
+
Parameters
+
+
+
steps
+
use steps to control the speed, so that it may be a scroll, or fling
Scrolls to the end of a scrollable layout element. The end can be at the
+ bottom-most edge in the case of vertical controls, or the right-most edge for
+ horizontal controls. Make sure to take into account devices configured with
+ right-to-left languages like Arabic and Hebrew.
Sets the percentage of a widget's size that's considered as no-touch
+ zone when swiping.
+ The no-touch zone is 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.
Specifies the elements in the layout hierarchy for tests to target, filtered
+ by properties such as text value, content-description, class name, and state
+ information. You can also target an element by its location in a layout
+ hierarchy.
Set the search criteria to match widgets that are checkable.
+
+ 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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);
+
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.
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.
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
+
+
+
val
+
Value to match
+
+
+
+
+
Returns
+
UiSelector with the specified search criteria
+
+
+
+
+
+
+
+
+
+
+
+ public
+
+
+
+
+ UiSelector
+
+ text
+ (String text)
+
+
+
+
+
+
+
+
+
+
+
+
+
Set the search criteria to match the visible text displayed
+ in a widget (for example, the text label to launch an app).
+
+ The text for the element must match exactly with the string in your input
+ argument. Matching is case-sensitive.
Set the search criteria to match the visible text in a widget
+ where the visible text must contain the string in your input argument.
+
+ The matching is case-sensitive.
Set the search criteria to match the visible text displayed in a layout
+ element, using a regular expression.
+
+ The text in the widget must match exactly with the string in your
+ input argument.
See registerWatcher(String, UiWatcher) on how to register a
+ a condition watcher to be called by the automation library. The automation library will
+ invoke checkForCondition() only when a regular API call is in retry mode because it is unable
+ to locate its selector yet. Only during this time, the watchers are invoked to check if there is
+ something else unexpected on the screen.
+ Custom handler that is automatically called when the testing framework is unable to
+ find a match using the UiSelector
+
+ When the framework is in the process of matching a UiSelector and it
+ is unable to match any widget based on the specified criteria in the selector,
+ the framework will perform retries for a predetermined time, waiting for the display
+ to update and show the desired widget.
+
+
+
+
Custom handler that is automatically called when the testing framework is unable to
+ find a match using the UiSelector
+
+ When the framework is in the process of matching a UiSelector and it
+ is unable to match any widget based on the specified criteria in the selector,
+ the framework will perform retries for a predetermined time, waiting for the display
+ to update and show the desired widget. While the framework is in this state, it will call
+ registered watchers' checkForCondition(). This gives the registered watchers a chance
+ to take a look at the display and see if there is a recognized condition that can be
+ handled and in doing so allowing the current test to continue.
+
+ An example usage would be to look for dialogs popped due to other background
+ processes requesting user attention and have nothing to do with the application
+ currently under test.
+
+
Returns
+
true to indicate a matched condition or false for nothing was matched
Returns a SearchCondition that is satisfied when at least one element matching the
+ selector can be found. The condition will return the first matching element.
+
Returns a SearchCondition that is satisfied when at least one element matching the
+ selector can be found. The condition will return all matching elements.
+
+
+ This class is deprecated.
+ It is no longer necessary to extend UiAutomatorTestCase. You can use
+ getInstance(Instrumentation) from any test class as long as you have access to
+ an Instrumentation instance.
+
+
+
+
+
+ Specifies the elements in the layout hierarchy for tests to target, filtered
+ by properties such as text value, content-description, class name, and state
+ information.
+
+
+
+
+ Generated in test runs when a UiSelector selector could not be matched
+ to any UI element displayed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/html/tools/help/index.jd b/docs/html/tools/help/index.jd
index 75324b79aa422df762908a745d698907c664686c..4c97d0c1bfa26f858273582130b6ee034d7d95ec 100644
--- a/docs/html/tools/help/index.jd
+++ b/docs/html/tools/help/index.jd
@@ -70,11 +70,6 @@ avd) the emulator (emulator), and the Dalvik Debug Monitor S
an emulator instance or connected Android-powered device. It also provides access to the
device shell for advanced command-line operations.
-
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.
Runs on your emulator or device and generates pseudo-random streams of user events such
-as clicks, touches, or gestures, as well as a number of system-level events. You can use the Monkey
-to stress-test applications that you are developing, in a random yet repeatable manner.
-
+ The Android Testing Support Library provides an extensive framework for testing Android apps.
+ This library provides a set of APIs that allow you to quickly build and run test code for
+ your apps, including JUnit 4 and functional user interface (UI) tests. You can run tests
+ created using these APIs from the Android Studio IDE or from the command line.
+
+
+
The Android Testing Support library is available through the Android SDK Manager.
+ For more information, see Testing Support Library Setup
+
+
+
+ This page provides information about what tools are provided in the Android Testing Support
+ Library, how to use them in your testing environment, and information about library releases.
+
+
+
+ Testing Support Library Features
+
+
+
+ The Android Testing Support Library includes the following test automation tools:
+
+ Espresso: UI testing framework; suitable for
+ functional UI testing within an app
+
+
+
+ UI Automator: UI testing framework; suitable
+ for cross-app functional UI testing across system and installed apps
+
+
+
+
+ AndroidJUnitRunner
+
+
+
+ The
+ {@code AndroidJUnitRunner}
+ class is a JUnit test runner that lets you
+ run JUnit 3 or JUnit 4-style test classes on Android devices, including those using the
+ Espresso and UI Automator testing frameworks.
+ The test runner handles loading your test package and the app under test
+ to a device, running your tests, and reporting test results. This class replaces the {@link
+ android.test.InstrumentationTestRunner} class, which only supports JUnit 3 tests.
+
+ The test runner is compatible with your JUnit 3 and JUnit 4 (up to JUnit
+ 4.10) tests. However, you should avoid mixing JUnit 3 and and JUnit 4 test code in the same
+ package, as this might cause unexpected results. If you are creating an instrumented JUnit 4
+ test class to run on a device or emulator, your test class must be prefixed with the
+ {@code @RunWith(AndroidJUnit4.class)} annotation.
+
+
+
The following code snippet shows how you might write an instrumented JUnit 4 test to validate
+ that the add operation in the {@code CalculatorActivity} class works correctly.
+
+
+
+import android.support.test.runner.AndroidJUnit4;
+import android.support.test.runner.AndroidJUnitRunner;
+import android.test.ActivityInstrumentationTestCase2;
+
+@RunWith(AndroidJUnit4.class)
+public class CalculatorInstrumentationTest
+ extends ActivityInstrumentationTestCase2<CalculatorActivity> {
+
+ @Before
+ public void setUp() throws Exception {
+ super.setUp();
+
+ // Injecting the Instrumentation instance is required
+ // for your test to run with AndroidJUnitRunner.
+ injectInstrumentation(InstrumentationRegistry.getInstrumentation());
+ mActivity = getActivity();
+ }
+
+ @Test
+ public void typeOperandsAndPerformAddOperation() {
+ // Call the CalculatorActivity add() method and pass in some operand values, then
+ // check that the expected value is returned.
+ }
+
+ @After
+ public void tearDown() throws Exception {
+ super.tearDown();
+ }
+}
+
+
+
+ Access to instrumentation information
+
+
+
+ You can use the
+ {@code InstrumentationRegistry}
+ class to access information related to your
+ test run. This class includes the {@link android.app.Instrumentation} object, target app {@link
+ android.content.Context} object, test app {@link android.content.Context} object, and the
+ command line arguments passed into your test. This data is useful when you are writing tests
+ using the UI Automator framework or when writing tests that have dependencies on the {@link
+ android.app.Instrumentation} or {@link android.content.Context} objects.
+
+
+
+ Test filtering
+
+
+
+ In your JUnit 4.x tests, you can use annotations to configure the test run. This feature
+ minimizes the need to add boilerplate and conditional code in your tests. In addition to the
+ standard annotations supported by JUnit 4, the test runner also supports Android-specific
+ annotations, including:
+
+
+
+
{@code @RequiresDevice}:
+ Specifies that the test should run only on physical devices, not on emulators.
+
+
+
{@code @SdkSupress}:
+ Suppresses the test from running on a lower Android API level than the given level. For
+ example, to suppress tests on all API levels lower than 18 from running, use the annotation
+ {@code @SDKSupress(minSdkVersion=18)}.
+
+
+
{@link android.test.suitebuilder.annotation.SmallTest @SmallTest},
+ {@link android.test.suitebuilder.annotation.MediumTest @MediumTest},
+ and {@link android.test.suitebuilder.annotation.LargeTest @LargeTest}: Classify how long
+ a test should take to run, and consequently, how frequently you can run the test.
+
+
+
+
+ Test sharding
+
+
+
+ The test runner supports splitting a single test suite into multiple
+ shards, so you can easily run tests belonging to the same shard together as a group,
+ under the same {@link android.app.Instrumentation} instance. Each shard is identified by an
+ index number. When running tests, use the {@code -e numShards} option to specify the number
+ of separate shards to create and the {@code -e shardIndex} option to specify which shard to
+ run.
+
+
+
+ For example, to split the test suite into 10 shards and run only the tests grouped in the
+ second shard, use the following command:
+
+ To learn more about using this test runner, see the
+ API reference.
+
+
+
+ Espresso
+
+
+
+ The Espresso testing framework provides a set of APIs to build UI tests to test user flows
+ within an app. These APIs let you write automated UI tests that are concise and that run
+ reliably. Espresso is well-suited for writing white box-style automated tests, where
+ the test code utilizes implementation code details from the app under test.
+
+
+
+ The key features of the Espresso testing framework include:
+
+
+
+
Flexible APIs for view and adapter matching in target apps.
+ For more information, see View matching.
+
+
An extensive set of action APIs to automate UI interactions.
+ For more information, see Action APIs.
+
+
+
UI thread synchronization to improve test reliability.
+ For more information, see UI thread synchronization.
+
+
+
+
Requires Android 2.2 (API level 8) or higher.
+
+
+ View matching
+
+
+
+ The {@code Espresso.onView()}
+ method lets you access a UI component in the target app and
+ interact with it. The method accepts a
+ {@code Matcher} argument and searches the view
+ hierarchy to locate a corresponding {@link android.view.View} instance that meets some given
+ criteria. You can refine searches by specifying such criteria as:
+
+
+
+
The class name of the view
+
+
+
The content description of the view
+
+
+
The {@code R.id} of the view
+
+
+
Text displayed in the view
+
+
+
+
+ For example, to target a button that has the ID value of {@code my_button}, you can specify
+ a matcher like this:
+
+
+
+onView(withId(R.id.my_button));
+
+
+ If the search is successful, the
+ {@code onView()}
+ method returns a reference which lets you
+ perform user actions and test assertions against the target view.
+
+
+
+ Adapter matching
+
+
+
+ In an {@link android.widget.AdapterView} layout, the layout is dynamically populated with
+ children views at runtime. If the target view is inside a layout subclassed from {@link
+ android.widget.AdapterView} (such as a {@link android.widget.ListView} or {@link
+ android.widget.GridView}), the
+ {@code onView()}
+ method might not work because only a subset of
+ the layout’s views may be loaded in the current view hierarchy.
+
+
+
+ Instead, use the {@code Espresso.onData()}
+ method to access a target view element. The {@code Espresso.onData()}
+ method returns a reference which lets you perform user actions and test assertions against the
+ elements in an {@link android.widget.AdapterView}.
+
+
+
+ Action APIs
+
+
+
+ Typically, you test an app by performing some user interactions against the app’s user
+ interface. You can easily automate these actions in your test by using the
+ {@code ViewActions}
+ API. You can perform such UI interactions as:
+
+// Type text into an EditText view, then close the soft keyboard
+onView(withId(R.id.editTextUserInput))
+ .perform(typeText(STRING_TO_BE_TYPED), closeSoftKeyboard());
+
+// Press the button to submit the text change
+onView(withId(R.id.changeTextBt)).perform(click());
+
+
+ UI thread synchronization
+
+
+
+ Tests on Android devices can fail randomly because of timing issues. This testing issue is
+ referred to as test flakiness. Prior to Espresso, the workaround was to insert a
+ sufficiently long sleep or timeout period into a test or to add code to keep retrying the
+ failing operation. The Espresso testing framework handles synchronization between the
+ {@link android.app.Instrumentation} and the UI thread; this removes the need for the previous
+ timing workarounds and ensures that your test actions and assertions run more reliably.
+
+
+
+ To learn more about using Espresso, see the
+ API reference.
+
+
+
+ UI Automator
+
+
+
+ The UI Automator testing framework provides a set of APIs to build UI tests that perform
+ interactions on user apps and system apps. The UI Automator APIs allows you to perform
+ operations such as opening the Settings menu or the app launcher in a test device. The UI
+ Automator testing framework is well-suited for writing black box-style automated
+ tests, where the test code does not rely on internal implementation details of the target
+ app.
+
+
+
+ The key features of the UI Automator testing framework include:
+
+
+
+
A viewer to inspect layout hierarchy.
+ For more information, see UI Automator Viewer.
+
+
An API to retrieve state information and perform operations on the target device.
+ For more information, see Access to device state.
+
+
APIs that support cross-app UI testing.
+ For more information, see UI Automator APIs .
+
+
+
+
Requires Android 4.3 (API level 18) or higher.
+
+
+ UI Automator Viewer
+
+
+
+ The {@code uiautomatorviewer} tool provides a convenient GUI to scan and analyze the UI
+ components currently displayed on an Android device. You can use this tool to inspect the
+ layout hierarchy and view the properties of UI components that are visible on the foreground
+ of the device. This information lets you create more fine-grained tests using UI Automator,
+ for example by creating a UI selector that matches a specific visible property.
+
+
+
+ The {@code uiautomatorviewer} tool is located in the {@code <android-sdk>/tools/}
+ directory.
+
+
+
+ Access to device state
+
+
+
+ The UI Automator testing framework provides a
+ {@code UiDevice}
+ class to access and perform operations on the device on which the target app is running. You
+ can call its methods to access device properties such as current orientation or display size.
+ The {@code UiDevice}
+ class also let you perform actions such as:
+
+
+
+
Change the device rotation
+
+
+
Press a D-pad button
+
+
+
Press the Back, Home, or Menu buttons
+
+
+
Open the notification shade
+
+
+
Take a screenshot of the current window
+
+
+
+
+ For example, to simulate a Home button press, call the {@code UiDevice.pressHome()} method.
+
+
+
+ UI Automator APIs
+
+
+
+ The UI Automator APIs allow you to write robust tests without needing to know about the
+ implementation details of the app that you are targeting. You can use these APIs to capture
+ and manipulate UI components across multiple apps:
+
+
+
+
{@code UiCollection}:
+ Enumerates a container's UI elements for the purpose of counting,
+ or targeting sub-elements by their visible text or content-description property.
+
+
+
{@code UiObject}:
+ Represents a UI element that is visible on the device.
+
+
+
{@code UiScrollable}:
+ Provides support for searching for items in a scrollable UI container.
+
+
+
{@code UiSelector}:
+ Represents a query for one or more target UI elements on a device.
+
+
+
{@code Configurator}:
+ Allows you to set key parameters for running UI Automator tests.
+
+
+
+
+ For example, the following code shows how you can write a test script that brings up the
+ default app launcher in the device:
+
+
+
+// Initialize UiDevice instance
+mDevice = UiDevice.getInstance(getInstrumentation());
+
+// Perform a short press on the HOME button
+mDevice().pressHome();
+
+// Bring up the default launcher by searching for
+// a UI component that matches the content-description for the launcher button
+UiObject allAppsButton = mDevice
+ .findObject(new UiSelector().description("Apps"));
+
+// Perform a click on the button to bring up the launcher
+allAppsButton.clickAndWaitForNewWindow();
+
+
+ To learn more about using UI Automator, see the
+ API reference.
+
+
+
+ Testing Support Library Setup
+
+
+
+ The Android Testing Support Library package is included with the latest version of the
+ Android Support Repository, which you can obtain as a supplemental download through the
+ Android SDK Manager.
+
+
+
+ To download the Android Support Repository through the SDK Manager:
+
In the SDK Manager window, scroll to the end of the Packages list, find the
+ Extras folder and, if necessary, expand to show its contents.
+
+
+
Select the Android Support Repository item.
+
+
+
Click the Install packages... button.
+
+
+
+
+ After downloading, the tool installs the Support Repository files to your existing Android
+ SDK directory. The library files are located in the following subdirectory of your SDK:
+ {@code <sdk>/extras/android/m2repository} directory.
+
+
+
+ The Android Testing Support Library classes are located under the
+ {@code android.support.test} package.
+
+
+
+ To use the Android Testing Support Library in your Gradle project, add these dependencies in
+ your {@code build.gradle} file:
+
+
+
+dependencies {
+ androidTestCompile 'com.android.support.test:testing-support-lib:0.1'
+ // Set this dependency to build and run Espresso tests
+ androidTestCompile 'com.android.support.test.espresso:espresso-core:2.0'
+ // Set this dependency to build and run UI Automator tests
+ androidTestCompile 'com.android.support.test.uiautomator:uiautomator-v18:2.0.0'
+}
+
+
To set
+{@code AndroidJUnitRunner}
+ as the default test instrumentation runner in your Gradle project, specify this dependency in
+ your {@code build.gradle} file:
+ It is strongly recommended that you use the Android Testing Support Library together with the
+ Android Studio IDE. Android Studio offers capabilities that support test
+ development, such as:
+
+
+
+
Flexible Gradle-based build system that supports dependency management for your test code
+
+
+
Single project structure to contain your unit and instrumented test code together with
+ your app source code
+
+
+
Support for deploying and running tests on virtual or physical devices, from a
+ command line or graphical user interface
+
+ Testing is a critical software development activity because it helps you
+ improve the quality of your apps, ensure better user satisfaction, and
+ reduce overall development time spent on fixing defects.
+
+
+
The following sections describe tools that help
+ you test your mobile apps for the Android platform.
+
+
This library provides a set of APIs that allow
+ you to quickly build and run test code for your apps, including JUnit 4 and functional user
+ interface (UI) tests. The Android Testing Support Library includes the following test automation
+ tools:
+
+
This tool runs on your emulator or device and generates pseudo-random streams of user
+events such as clicks, touches, or gestures, as well as a number of system-level events. You can
+use the Monkey tool to stress-test applications that you are developing, in a random yet
+repeatable manner.
+
This testing system provides an API for writing programs that control an Android device or
+emulator from outside of Android code.
+
+
\ No newline at end of file
diff --git a/docs/html/tools/tools_toc.cs b/docs/html/tools/tools_toc.cs
index fa6328eae2fd170e714b58e560b0766a25e5a9c9..3f4b11169f99e44b3556dba4211d76da98a19c64 100644
--- a/docs/html/tools/tools_toc.cs
+++ b/docs/html/tools/tools_toc.cs
@@ -166,37 +166,11 @@
+ 
+ 
+ 