Espresso-Web is an entry point to work with Android WebView UI components. Espresso-Web reuses Atoms from the popular WebDriver API to examine and control the behavior of a WebView.
When to use Espresso-Web
Use Espresso-Web to test your hybrid apps, especially the integration of your
app’s native UI components with its
UI components. You can use the Espresso-Web API in conjunction with other
Espresso APIs to fully interact with web elements inside
If you need to test only the
WebView itself, and not the
interactions between the
WebView and native components in your app, consider
writing a general web test using a framework like WebDriver. If you use a web testing framework, you don’t
need to use an Android device or a Java Virtual Machine, which makes your tests
run more quickly and reliably. That being said, Espresso-Web allows you to reuse
your custom WebDriver atoms, which gives you a lot of flexibility, especially
when writing tests that you plan to run against both standalone web apps and
apps that include an Android UI.
How it works
Similarly to Espresso’s
WebView interaction comprises several Atoms.
WebView interactions use a combination of the Java programming language and a
Espresso sees on the Java-based side is an isolated copy—returning data from
objects is fully supported, allowing you to verify all data that’s returned from
What is a WebDriver Atom?
The WebDriver framework uses Atoms to find and manipulate web elements
programmatically. Atoms are used by WebDriver to allow browser manipulation. An
Atom is conceptually similar to a
a self-contained unit that performs an action in your UI. You expose Atoms using
a list of defined methods, such as
getElement(), to drive
the browser from the user’s point of view. However, if you use the WebDriver
framework directly, Atoms need to be properly orchestrated, requiring logic that
is quite verbose.
Within Espresso, the classes
wrap this boilerplate and give an Espresso-like feel to interacting with WebView
objects. So in a context of a
WebView, Atoms are used as
a substitution to traditional Espresso
The API then looks quite simple:
onWebView() .withElement(Atom) .perform(Atom) .check(WebAssertion);
To learn more, read Selenium’s documentation on Atoms.
To include Espresso-Web in your project, complete the following steps:
- Open your app’s
build.gradlefile. This is usually not the top-level
Add the following line inside dependencies:
Espresso-Web is only compatible with Espresso 2.2 or higher and the Android Testing Support Library 0.3 or higher, so make sure you update those lines as well:
androidTestCompile 'com.android.support.test:runner:1.0.2' androidTestCompile 'com.android.support.test:rules:1.0.2' androidTestCompile 'com.android.support.test.espresso:espresso-core:3.0.2'
Common API usage
method is the main entry point when working with WebView on Android using
Espresso. You use this method to perform Espresso-Web tests, such as the
onWebView() .withElement(findElement(Locator.ID, "link_2")) // similar to onView(withId(...)) .perform(webClick()) // Similar to perform(click()) // Similar to check(matches(...)) .check(webMatches(getCurrentUrl(), containsString("navigation_2.html")));
In this example, Espresso-Web locates a DOM element whose ID is
clicks on it. The tool then verifies that the WebView sends a GET request
the ActivityTestRule and calling
necessary to ensure that AndroidJUnitRunner
Common web interactions
Common interactions with
Web.WebInteraction objects include the following:
withElement()references a DOM element within the WebView.
withContextualElement()references a scoped DOM element within the WebView, relative to another DOM element. You should call
withElement()first to establish the reference
Web.WebInteractionobject (DOM element).
onWebView() .withElement(findElement(Locator.ID, "teacher")) .withContextualElement(findElement(Locator.ID, "person_name"));
check()evaluates a condition, making sure that it resolves to
onWebView() .withElement(findElement(Locator.ID, "teacher")) .withContextualElement(findElement(Locator.ID, "person_name")) .check(webMatches(getText(), containsString("Socrates")));
perform()executes an action within a WebView, such as clicking on an element.
onWebView() .withElement(findElement(Locator.ID, "teacher")) .perform(webClick());
reset()reverts the WebView to its initial state. This is necessary when a prior action, such as a click, introduces a navigation change that makes ElementReference and WindowReference objects inaccessible.
Note: Although using
reset()is useful when making assertions against multi-page workflows, such as form submissions, your tests should usually be limited in scope and focus on a single page.
onWebView() .withElement(...) .perform(...) .reset();
The following example tests whether, after entering text into a WebView and selecting a Submit button, the same text appears within a different element in the same WebView:
See also the Espresso Web sample on GitHub.