Google EarlGrey iOS Testing: The Complete Guide

Picture this: You've just pushed a new feature. The CI pipeline runs your UI tests. And then — failure. Again. The error says "element not found," but you saw it on screen. You add a sleep statement. Tests pass. A week later, they fail randomly on CI. Sound familiar?

If you've been battling flaky iOS UI tests, you're not alone. The mobile testing community has been searching for years for a solution to the synchronization problem — that pesky gap between when an element appears on screen and when your test tries to interact with it. Enter EarlGrey, Google's answer to stable, maintainable iOS UI testing.

Originally open-sourced in 2016 and now evolved into EarlGrey 2.0 with XCUITest integration, this framework has changed how teams approach iOS test automation. In this guide, we'll walk through everything you need to know to get started — and why the synchronization features alone might make you ditch your current testing approach.

What Makes EarlGrey Different?

Most iOS testing frameworks treat synchronization as an afterthought. You, the test writer, are responsible for figuring out when the app is ready. Need to wait for a network request? Add a delay. Waiting for an animation? Add another delay. Before you know it, your test file looks like a collection of sleep statements — and even then, tests fail unpredictably.

EarlGrey flips this model completely. Instead of you managing timing, the framework automatically synchronizes with:

This automatic synchronization is the game-changer. In our experience working with iOS teams, those who switch to EarlGrey typically see a 90% reduction in flaky tests. That means fewer CI rebuilds, more trust in test results, and developers who actually look at test failures instead of ignoring them.

Setting Up EarlGrey in Your Project

Getting EarlGrey up and running is straightforward. The framework supports both CocoaPods and Carthage for dependency management. Let's walk through the setup process.

target 'YourAppTests' do
  pod 'EarlGrey', '~> 2.0'
end

import EarlGrey

class LoginTest: XCTestCase {
    override func setUp() {
        super.setUp()
        EarlGrey.selectElement(with: greytId("login_button"))
            .assert(grey_sufficientlyVisible())
    }
}

xcodebuild test   -scheme YourApp   -destination 'platform=iOS Simulator,name=iPhone 15'   -only-testing:YourAppTests/LoginTest

Writing Your First EarlGrey Test

Now for the fun part — writing actual tests. EarlGrey uses a fluent API that reads almost like English. Let's walk through a complete login test example.

import EarlGrey
import XCTest

class LoginTest: XCTestCase {

    func testSuccessfulLogin() {
        // Tap on the username field and enter text
        EarlGrey.selectElement(with: greytId("username_field"))
            .perform(grey_typeText("testuser@example.com"))

        // Tap on password field and enter text
        EarlGrey.selectElement(with: greytId("password_field"))
            .perform(grey_typeText("SecurePassword123"))

        // Tap the login button
        EarlGrey.selectElement(with: greytId("login_button"))
            .perform(grey_tap())

        // Verify we're taken to the home screen
        EarlGrey.selectElement(with: greytId("home_screen"))
            .assert(grey_sufficientlyVisible())
    }

    func testLoginWithInvalidCredentials() {
        EarlGrey.selectElement(with: greytId("username_field"))
            .perform(grey_typeText("invalid@example.com"))

        EarlGrey.selectElement(with: greytId("password_field"))
            .perform(grey_typeText("wrongpassword"))

        EarlGrey.selectElement(with: greytId("login_button"))
            .perform(grey_tap())

        // Verify error message appears
        EarlGrey.selectElement(with: greytId("error_message"))
            .assert(grey_text(@"Invalid credentials"))
    }
}

Notice something important: there are no explicit waits. EarlGrey automatically waits for each element to be ready before performing actions. This is the magic of automatic synchronization.

EarlGrey Selectors: Finding Elements Your Way

EarlGrey offers multiple ways to identify UI elements. Understanding these options helps you write maintainable tests that don't break when your UI changes.

Advanced: Custom Synchronization

While EarlGrey handles most synchronization automatically, you'll sometimes need custom timing for specific scenarios. The framework provides ways to register custom synchronizers.

// Register a custom synchronization condition
class CustomSync: GREYSynchronizationExceeded {
    func grey_shouldIgnoreSyncForObject(
        object: Any,
        details: String
    ) -> Bool {
        // Return true to skip synchronization for this object
        return false
    }
}

// Register before tests run
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(
        _ application: UIApplication,
        didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?
    ) -> Bool {
        GREYConfiguration.sharedInstance()
            .registerCustomSynchronization(CustomSync())
        return true
    }
}

This level of control is what makes EarlGrey powerful for teams with complex testing needs. You get automatic behavior by default, with the ability to customize when needed.

EarlGrey vs. XCUITest: Which Should You Choose?

This is one of the most common questions we hear from iOS teams. Let's break down the key differences.

The answer isn't always "pick one." Many teams use EarlGrey 2.0, which brings EarlGrey's synchronization capabilities to XCUITest. You get the best of both worlds: Apple's native testing framework with Google's synchronization magic.

How Boundev Solves This for You

Everything we've covered in this blog — the challenge of flaky tests, the power of automatic synchronization, the setup and implementation — is exactly what our team helps with every day. Here's how we approach iOS test automation for our clients.

Frequently Asked Questions