How to Get Started with EarlGrey – iOS Functional UI Testing Framework

Dear Testdroiders,

Few weeks ago Google announced in their blog that they have open sourced their internal iOS test automation framework called EarlGrey. 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 on what EarlGrey really is about.


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 script tries to interact with the UI of application. The similar feature is available for example in Google Espresso for Android and actually that makes the performance very smooth and fast as 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 fast and robust approach to ensure UI testing goes through as clicks, gestures and other user interactions do not get done if UI element is not fully shown.

Setting Up EarlGrey and Running a Demo

First, clone the EarlGrey source repository from Github:

git clone

This projects 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 and after that the framework is usable for your test script creation. You might get some update notifications so just click Perform Changes.

Screen Shot 2016-03-01 at 11.59.28 AM

Depending on which device and OS version you want to run 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 few example 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 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 vs. EarlGrey for iOS

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 you think about EarlGrey? Weigh in with a comment below!

Happy EarlGrey Testing Folks!

The Beginner’s Guide of Using Appium for Mobile App Testing

Learn all the basics about Appium, how to set it up and how to use it for mobile app testing.


  • Eri

    Now, Google must create framework that will be allow create test on both platforms and have to name them YerbaMate

  • govindrajput

    It was a very interesting article so I read this post and I like it, 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.

  • This is really interesting to know about EarlGrey… yes it has good docs…many APIs and App sync. However, what is your take on not choosing this over XCUItest given that its so mature and Apple is showing it love and that its out of the process and which is really making it like ideal for UI test where the tester(framework) need not be aware of App state like the manual tester.

  • How do we launch any other app e.g. Settings and operate on them from EarlGrey test?