EarlGrey 2 — White-box UI Testing framework for iOS

Szymon Kazmierczak
Nov 29 · 3 min read

EarlGrey 2 is an automated UI testing framework developed at Google. What sets it apart from other iOS UI testing frameworks? Let’s have a look at it’s description from their own readme:

- Synchronisation: From run to run, EarlGrey 2.0 ensures that you will get the same result in your tests, by making sure that the application is idle. It does so by automatically tracking UI changes, network requests and various queues. EarlGrey 2.0 also allows you to manually implement custom timings.
- White-box: EarlGrey 2.0 allows you to query the application under test from your tests.
- Native Development: As with EarlGrey 1.0, you can use EarlGrey 2.0 natively with Xcode. You can run tests directly from Xcode or xcodebuild. Please note that EarlGrey 2.0 uses a UI Testing Target and not a Unit Testing Target like EarlGrey 1.0.

All three points are big improvements over other UI testing frameworks (such as XCUITest). Let’s walk through them one by one:

In XCUITest, you can use XCTest’s waitForExpectations to wait for a condition to be met. While XCUITest also has some built in polling (such as waitForQuiescenceIncludingAnimationsIdle ), it is not nearly as comprehensive as EarlGreys.

With EarlGrey2, you get multiple synchronisation options out of the box — network, animations, UI states etc.
EarlGrey also provides capability to define your own custom synchronisation trackers (akin to Idling Resources in Espresso), however I have not felt the need yet to implement my own tracker as things work perfectly with just the base trackers.

2.White-Box Testing Capability
My main gripe with XCUITest is that it’s pure black-box — To configure the app for testing, you need to set the state before launching the app through launch arguments and environment variables. Then, you have to parse those env vars and launch arguments in your main (not test) codebase via e.g. CommandLine.arguments.contains(“-reset"),polluting the production code.

Now what if you could expose the app under test to your UI testing target and change things before launching the app, and also at any point in it’s lifecycle? That’s what EarlGrey2 offers through it’s white-box testing capability. EarlGrey 2’s docs have a great explanation of how it’s done over here.

My main use cases for the white-box testing capability have been to clear the app state (removing the need to reinstall the app for each test), change network mocks on the fly, and set Rollout flags for feature toggling.

3.Native Development
With EarlGrey, you’re writing tests in a UI Testing Target of your Xcode Project. Having your tests tightly integrated with the production codebase gives you a lot of benefits, biggest of which are the ability to run and configure the tests directly from Xcode, and write the tests using obj-c or Swift version that matches your project configuration.

Does that sound interesting?

In the follow up blog posts, I’ll go through:

  • Integrating EarlGrey 2 with an iOS app using direct project copy.
  • Writing your first tests with EarlGrey 2 while leveraging the XCUITest’s XCUIApplication.

As well as some advanced usage of EarlGrey2, such as:

  • Making use of the white-box testing capability

I’m also open to suggestions — if there’s something you’d like to see, send me a message!

Link to the repository: https://github.com/google/EarlGrey/tree/earlgrey2


Best practices, quality assurance, software engineering, career and more

Szymon Kazmierczak

Written by

Software Development Engineer in Test


Best practices, quality assurance, software engineering, career and more

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade