class Espresso


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

Summary

Public functions

java-static Unit

Closes soft keyboard if open.

java-static (Mutable)List<IdlingResource!>!

This function is deprecated.

use getResources instead.

java-static DataInteraction!

Creates an DataInteraction for a data object displayed by the application.

java-static Unit

Loops the main thread until the app goes idle.

java-static T!
<T> onIdle(action: Callable<T!>!)

Loops the main thread until the app goes idle.

java-static ViewInteraction!

Creates a ViewInteraction for a given view.

java-static Unit

Opens the overflow menu displayed within an ActionBar.

java-static Unit

Opens the overflow menu displayed in the contextual options of an ActionMode.

java-static Unit

Press on the back button.

java-static Unit

Similar to pressBack but will not throw an exception when Espresso navigates outside the application or process under test.

java-static Boolean

This function is deprecated.

use register instead.

java-static Unit

This function is deprecated.

use registerLooperAsIdlingResource instead.

java-static Unit
registerLooperAsIdlingResource(looper: Looper!, considerWaitIdle: Boolean)

This function is deprecated.

use registerLooperAsIdlingResource instead.

java-static Unit

Changes the default FailureHandler to the given one.

java-static Boolean

This function is deprecated.

use unregister instead.

Public functions

closeSoftKeyboard

java-static fun closeSoftKeyboard(): Unit

Closes soft keyboard if open.

getIdlingResources

java-static fun getIdlingResources(): (Mutable)List<IdlingResource!>!

Returns a list of all currently registered IdlingResources.

onData

@CheckReturnValue
java-static fun onData(dataMatcher: Matcher<Any!>!): DataInteraction!

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

This method builds a DataInteraction object - it does not interact with the application under test at all. It is expected that the caller use the ViewInteraction object to perform an action or assertion.

Parameters
dataMatcher: Matcher<Any!>!

a matcher used to find the data object.

Returns
DataInteraction!

a DataInteraction that will perform an action or assertion.

onIdle

java-static fun onIdle(): Unit

Loops the main thread until the app goes idle.

Only call this method for tests that do not interact with any UI elements, but require Espresso's main thread synchronisation! This method is mainly useful for test utilities and frameworks that are build on top of Espresso.

For UI tests use onView or onData. These APIs already use Espresso's internal synchronisation mechanisms and do not require a call to onIdle.

Throws
androidx.test.espresso.AppNotIdleException

when app does not go Idle within the master policies timeout.

java.lang.RuntimeException

when being invoked on the main thread.

onIdle

java-static fun <T> onIdle(action: Callable<T!>!): T!

Loops the main thread until the app goes idle.

Same as onIdle, but takes an additional Callable as parameter, which is executed after the app goes idle. This works on any thread, including the main thread.

Parameters
action: Callable<T!>!

callable executed when the app goes idle.

Returns
T!

the computed result of the action callable.

Throws
androidx.test.espresso.AppNotIdleException

when app does not go Idle within the master policies timeout.

onView

@CheckReturnValue
java-static fun onView(viewMatcher: Matcher<View!>!): ViewInteraction!

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.

This method builds a ViewInteraction object - it does not interact with the application under test at all. It is expected that the caller use the ViewInteraction object to perform an action or assertion.

Parameters
viewMatcher: Matcher<View!>!

used to select the view.

See also
onData

openActionBarOverflowOrOptionsMenu

java-static fun openActionBarOverflowOrOptionsMenu(context: Context!): Unit

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.

openContextualActionModeOverflowMenu

java-static fun openContextualActionModeOverflowMenu(): Unit

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.

pressBack

java-static fun pressBack(): Unit

Press on the back button.

Throws
androidx.test.espresso.PerformException

if currently displayed activity is root activity, since pressing back button would result in application closing.

pressBackUnconditionally

java-static fun pressBackUnconditionally(): Unit

Similar to pressBack but will not throw an exception when Espresso navigates outside the application or process under test.

registerIdlingResources

java-static fun registerIdlingResources(resources: Array<IdlingResource!>!): Boolean

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.

Returns
Boolean

true if all resources were successfully registered

registerLooperAsIdlingResource

java-static fun registerLooperAsIdlingResource(looper: Looper!): Unit

Registers a Looper for idle checking with the framework. This is intended for use with non-UI thread loopers.

Throws
java.lang.IllegalArgumentException

if looper is the main looper.

registerLooperAsIdlingResource

java-static fun registerLooperAsIdlingResource(looper: Looper!, considerWaitIdle: Boolean): Unit

Registers a Looper for idle checking with the framework. This is intended for use with non-UI thread loopers.

This method allows the caller to consider Thread.State.WAIT to be 'idle'.

This is useful in the case where a looper is sending a message to the UI thread synchronously through a wait/notify mechanism.

Throws
java.lang.IllegalArgumentException

if looper is the main looper.

setFailureHandler

java-static fun setFailureHandler(failureHandler: FailureHandler!): Unit

Changes the default FailureHandler to the given one.

unregisterIdlingResources

java-static fun unregisterIdlingResources(resources: Array<IdlingResource!>!): Boolean

Unregisters one or more IdlingResources. If any of the given resources are not already registered, a warning is logged.

Returns
Boolean

true if all resources were successfully unregistered