EarlGrey: Google's iOS UI Automation Framework, and What the Deprecation Notice Means for You

What EarlGrey Solves, and Why Synchronization Is the Whole Point

Flaky UI tests usually fail for one reason: the test acts before the app is ready. A tap lands while a network response is still in flight, or an animation has not settled, and the assertion fails for reasons unrelated to the code under test. EarlGrey's stated purpose is to remove that class of failure. The README says the framework automatically synchronizes with the UI, network requests and various queues, and that this synchronization ensures the UI is in a steady state before actions are performed. It also says manual custom timings remain possible when the automatic behavior is not what you want.

The audience is narrow and specific. This is not a cross-platform tool, and it is not a black-box runner driven from outside the app. It is a native iOS framework written in Objective-C that works in conjunction with XCTest and integrates with Xcode's Test Navigator, so tests run from Xcode or from the command line with xcodebuild. If your team writes iOS tests in Swift or Objective-C inside an Xcode test target, you are the intended user. If you need one test suite covering iOS and Android, EarlGrey is the wrong starting point, because the entire design assumes XCTest and the iOS runtime.

How EarlGrey Synchronizes: Automatic Waiting With a Manual Escape Hatch

The mechanism described in the README is a synchronization layer that sits between your test code and the app. Before an action is performed, the framework waits for the app to reach a steady state, and that wait covers three sources of pending work: the UI, network requests, and queues. The payoff the README claims is stability and repeatability, which is the opposite of the sleep-and-hope pattern common in hand-written UI tests.

The design choice worth noticing is that automatic synchronization is not presented as mandatory. The README states that EarlGrey still allows you to manually implement customized timings if needed. That matters in practice: apps with continuous animation, long-polling connections, or background queues that never fully drain can defeat any idle-detection heuristic, and having a manual path means you are not stuck. The cost is that a manually tuned timing is exactly the kind of fragile construct the framework exists to remove, so it should be the exception.

EarlGrey also collects usage data. According to the README, the framework uploads the MD5 hash of the bundle ID, test class names and test method names to Google Analytics, and the implementation details live in GREYAnalytics.m. Hashing means the raw identifiers are not sent, but the volume and shape of your test suite are. The README documents an opt-out, which is covered below.

Installing EarlGrey and Running a First Test

The README points users to the docs folder for installation, specifically docs/install-and-run.md, and warns against skipping the backward compatibility page. It does not reproduce the full install steps inline, so treat the repository docs as the source of truth for your Xcode version.

For contributors working on the framework itself, the README gives this sequence. Clone the repository, then run the setup script to fetch dependencies:

git clone https://github.com/google/EarlGrey.git

After cloning, the README says to download all dependencies using setup-earlgrey.sh, which lives in the Scripts directory. Once that script completes successfully, open EarlGrey.xcodeproj and confirm that all targets build. That project is for making changes to the framework, not for consuming it in an app.

The README also documents two test projects for people adding tests to EarlGrey itself. Unit tests live in Tests/UnitTests and use UnitTests.xcodeproj; functional tests live in Tests/FunctionalTests and use FunctionalTests.xcodeproj. In both cases you select the matching scheme and press Cmd+U to run everything.

If you want to disable the analytics collection described earlier, the README shows the config key to set in your test's setUp method. In Objective-C:

// Disable analytics.
[[GREYConfiguration sharedInstance] setValue:@(NO) forConfigKey:kGREYConfigKeyAnalyticsEnabled];

The Swift equivalent uses the same key, GREYConfiguration.sharedInstance().setValue(false, forConfigKey: kGREYConfigKeyAnalyticsEnabled). Set it once in setUp and every test in the class inherits the setting.

The Deprecation Notice Is the Real Adoption Decision

The first line of the README is a deprecation notice, and it is the most important thing on the page. EarlGrey 1.0 is deprecated in favor of EarlGrey 2.0, which integrates it with XCUITest, and the README directs readers to the earlgrey2 branch. It also states plainly that EarlGrey 1.0 is not being maintained internally with iOS 13. That is a hard boundary, not a soft warning: the version most tutorials and older blog posts describe is the one the maintainers have moved past.

The practical consequence is that any evaluation has to start by choosing a branch. The master branch you land on by default carries the deprecated 1.0 line, while the earlgrey2 branch is where the current work is described. The repository itself is not archived and the last push was on 2026-09-15, so the project is not dormant, but that activity does not change the version split documented in the README.

Release naming reinforces the split. The recent releases listed are 2.2.2 from 2022-06-07, 2.2.1 from 2020-12-11 and 2.2.0 from 2020-10-20. The 2.x line has not seen a tagged release in years, which does not mean the branch is untouched, only that release tags are not the signal to watch here. Check the branch, not the release page.

Where EarlGrey Fails You

The clearest failure mode is version drift. If you follow the master branch README onto a modern iOS target, you are working against a line the README says is not maintained internally with iOS 13. Tests that passed on an older simulator can break for framework reasons rather than app reasons, and the fix may simply not exist on that branch.

The second limitation is scope. EarlGrey is iOS-only and XCTest-only by design. Nothing in the README suggests a path to Android, to web views driven from outside the app, or to a language other than Objective-C or Swift inside an Xcode test target. A team that needs one automation stack across platforms will end up maintaining two, and the iOS half will be the one with the smaller hiring pool.

The third is the synchronization model itself. Automatic waiting on network requests and queues is a strong default, but it assumes the app eventually goes idle. Apps with persistent connections or constant animation can keep the framework waiting, and the documented answer is manual custom timings, which puts you back in the business of guessing. Finally, the analytics collection is on by default and has to be disabled explicitly, which some organizations will treat as a compliance question rather than a preference.

EarlGrey Compared With XCUITest and Appium

The most direct alternative is XCUITest on its own, and the comparison is not hypothetical: the README says EarlGrey 2.0 integrates EarlGrey with XCUITest. That tells you the two are not rivals so much as layers. Plain XCUITest gives you Apple's supported automation surface with no third-party dependency and no analytics collection, but it does not ship the automatic synchronization with network requests and queues that EarlGrey describes as its main feature. Choosing between them is choosing between fewer moving parts and less waiting logic to write yourself.

The other common alternative is Appium, which drives the app from outside through the WebDriver protocol and supports multiple platforms from one test suite. That is a genuinely different approach: Appium's value is breadth and language choice, while EarlGrey's is depth inside a single app process, where it can observe queues and network activity that an external driver cannot see. If your tests must run unchanged against iOS and Android, Appium's model fits and EarlGrey's does not. If your tests are iOS-only and flakiness is the problem you are actually trying to solve, the synchronization layer is the reason to pick EarlGrey.

Maintenance, Licensing and What to Check Before Committing

Maintenance status has to be read carefully here. The repository is not archived, and the last push was on 2026-09-15, so commits are still landing. But the README's own deprecation notice says EarlGrey 1.0 is not being maintained internally with iOS 13, and the newest tagged release, 2.2.2, dates from 2022-06-07. The honest summary is that the project is alive on the earlgrey2 branch and effectively frozen on master. Plan your upgrade path around the branch, and expect to read source rather than release notes when something breaks.

On licensing, the repository carries Apache-2.0, and the README also shows a CC BY 4.0 badge pointing at the same LICENSE file. Apache-2.0 is a permissive licence that generally allows commercial use and modification with attribution and notice requirements. This is a description of what the repository states, not legal advice; if your organization has a licence review process, hand it the LICENSE file and the two badges rather than a summary.

The analytics behavior is the other item for that review. The framework uploads MD5 hashes of bundle ID, test class and test method names to Google Analytics by default, with the opt-out shown above. Decide whether that is acceptable before your first test run, not after.

Editorial conclusion

Adopt EarlGrey only after deciding which version you are adopting: the README states that EarlGrey 1.0 is deprecated in favor of EarlGrey 2.0 on the earlgrey2 branch, and that 1.0 is not maintained internally with iOS 13. Teams on modern iOS should read the earlgrey2 branch and its install guide before writing a single test. Teams that cannot move off XCUITest's own synchronization model, or that need a cross-platform runner, should not adopt it at all. Verify first that your Xcode and iOS target versions are covered by the branch you pick, and check whether the analytics opt-out key is set in your test's setUp method.

Frequently asked questions

Official sources

1. google/EarlGrey on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases