Skip to content

A few weeks ago Google announced in their blog that they have open-sourced their internal iOS test automation framework called EarlGrey for UI testing. As this is used internally with Google’s functional app testing and for example, YouTube, Calendar, Photos, Play Music and some others are getting tested using this framework. Naturally, we have tested this framework out and it seems an interesting choice as a test automation framework suitable for several types of apps as well. There are lots of similarities between EarlGrey for iOS and Espresso for Android so let’s have a glance at what EarlGrey really means for iOS functional UI testing.


Key Features and ‘New Things’ in EarlGrey

One of the difficulties that developers have experienced with some of existing test automation frameworks has been around the synchronization of the app and the instrumentation. Furthermore, getting tests running against app as synchronized and advance only when UI elements are visible on the screen has caused issues for many developers. If you are also considering XCTest/XCUITest, download our free guide to get started and how to create reliable tests.

One of the key implementation and feature in EarlGrey is the built-in synchronization that makes test scripts to wait for UI events to occur before the script tries to interact with the UI of application. The similar feature is available for example in Google Espresso for Android and that makes the performance very smooth and fast as the script doesn’t need to have any waits or other implementation that makes the test script run slower. In addition, this sort of implementation makes the test script more concise as all steps of the test script are showing how the test will proceed and UI gets synchronized with it.

Another important thing in EarlGrey is that all actions on UI elements are happening only on visible elements. As said, this will provide a fast and robust approach to ensure UI testing goes through as clicks, gestures and other user interactions do not get done if the UI element is not fully shown.

Setting Up EarlGrey for iOS UI testing

First, clone the EarlGrey source repository from Github:

git clone

This project includes all scripts to build and fetch dependencies, so after you’ve cloned the repository just run the setup script Scripts/ This fetches at least fishhook, OCHamcrestIOS.framework and OCmock.

Now you can jump on Xcode and open the EarlGrey.xcodeproj provided with the project. Check that all targets build properly, after which the framework can be used for your test script creation. You might get some update notifications so just click Perform Changes.

set up earlgrey for ios functional ui testing

Depending on which device and OS version you want to run the test on you have to configure and build settings accordingly. Here is the tutorial for configuring Xcode project for distribution.

The package includes examples of unit tests and functional tests. Both of the .xcodeproj files are under Tests folder. For more specific information about how to add unit and functional tests for your project please check the documentation provided with the package. The files are available under docs folder.

Then, let’s look at the demo provided with the project. Open EarlGreyExample.xcodeproj under Demo/EarlGreyExample. The project structure is as follows:

Screen Shot 2016-03-01 at 12.15.02 PM

EarlGrey Syntax

You can find some code examples under the project as well as example tests in EarlGreyExampleTests.m.

Similarly to Google Espresso, EarlGrey also contains matchers that are available from the GREYMatcher class. The documentation recommends using UI elements with those accessibility parameters and we’ll use a few examples here to show how those can be found. It seems that the best way to identify UI element is to use those accessibility identifiers as then those UI elements can be identified uniquely.

For identifying UI element you can use grey_accessibilityID() and also some accessibility properties as matchers. The syntax of EarlGrey with matchers goes as follows:

- (void)testBasicSelection {
  [EarlGrey selectElementWithMatcher:grey_accessibilityID(@"ClickHere")];

This selects the button that contains accessibility ID ‘ClickHere‘. The following line adds a tap on that specific button:

- (void)testBasicSelectionAndAction {
  [[EarlGrey selectElementWithMatcher:grey_accessibilityID(@"ClickHere")]

So using performAction:grey_tap() will do a click on the button specified with accessibility ID of ‘ClickHere’. Furthermore, you can also check whether UI element is fully visible using grey_sufficientlyVisible():

- (void)testBasicSelectionAndAssert {
  [[EarlGrey selectElementWithMatcher:grey_accessibilityID(@"ClickHere")]

This will assert execution until the button is visible.

Here is another example with GREYMatchers and UI selection calls: the following lines of code find the UI element that has accessibility label ‘Click‘ and verifies that the UI element is shown on the screen:

id visibleSendButtonMatcher =
    grey_allOf(grey_accessibilityLabel(@"Click"), grey_sufficientlyVisible(), nil);
[[EarlGrey selectElementWithMatcher:visibleSendButtonMatcher]

For any modifications on the increase or decrease of time for synchronization, GREYConfiguration file can be modified. The parameters (bolded) provided by default can be changed to any e.g. with these lines:

[self setDefaultValue:@(30.0) forConfigKey:kGREYConfigKeyInteractionTimeoutDuration];
[self setDefaultValue:@YES forConfigKey:kGREYConfigKeySynchronizationEnabled];

Espresso for Android UI testing vs. EarlGrey for iOS UI testing

As said, there are lots of similarities between EarlGrey and Espresso – and both seem to work well for their native platforms. Naturally the syntax is very different when comparing Java with Objective-C/Swift but we believe this can be a powerful test automation framework for some types of native apps on iOS. What do you think about EarlGrey? Weigh in with a comment below!

Happy EarlGrey Testing Folks!

Ville-Veikko Helppi

Mobile Testing Product Expert