EarlGrey — iOS UI Automation Test Framework by Google

Introduction

EarlGrey is a native iOS UI testing framework developed by Google. Unlike XCUITest which runs in a separate process, EarlGrey runs within the application process itself, giving it direct access to UI state and enabling automatic synchronization with animations, network requests, and dispatch queues. This architecture reduces test flakiness by eliminating the need for manual sleep calls or explicit waits.

What EarlGrey Does

• Automatically synchronizes test actions with app animations, network calls, and main-thread dispatch queues to eliminate flaky waits
• Provides a matcher-based API for identifying UI elements by accessibility properties, text content, class type, or custom predicates
• Runs within the app process for direct access to view hierarchies, enabling precise element interaction
• Supports white-box testing patterns where tests can inspect and modify app state during execution
• Integrates with Xcode's XCTest framework so tests run alongside standard unit tests

Architecture Overview

EarlGrey 2.0 splits into two components: a test-side library that provides the matcher and assertion API (linked into the XCTest bundle), and an app-side library that handles synchronization and UI interaction (linked into the app target). Communication between the two happens via eDistantObject, an inter-process communication layer. The synchronization engine monitors the app's run loop, tracking pending animations (CAAnimation), active network requests (NSURLSession), and queued dispatch blocks. Test actions are only executed when the app reaches an idle state, ensuring reliable interaction timing.

Self-Hosting & Configuration

• Install via CocoaPods or Swift Package Manager into your Xcode project
• Add the EarlGrey test library to your XCTest target and the app component to your main app target
• Configure synchronization timeouts and custom idle resources in the test setUp method
• Runs on both iOS simulators and physical devices through Xcode's test runner
• Integrates with CI systems like GitHub Actions, Jenkins, and Bitrise using xcodebuild test

Key Features

• Automatic synchronization eliminates manual waits, reducing test flakiness from timing issues
• White-box testing capability: access app internals, mock dependencies, and modify state during tests
• Composable matchers that combine accessibility ID, text, class, and custom predicates for precise element selection
• Assertion library for verifying visibility, enabled state, text content, and custom conditions
• Support for gesture simulation including swipe, pinch, rotation, and long press

Comparison with Similar Tools

• XCUITest — Apple's built-in UI testing runs out-of-process; EarlGrey runs in-process with automatic synchronization for lower flakiness
• Appium — Cross-platform mobile testing via WebDriver protocol; EarlGrey is iOS-native with faster execution and deeper integration
• Detox — React Native testing framework with synchronization; EarlGrey targets native iOS apps with similar sync guarantees
• KIF — Another iOS testing framework that interacts via accessibility APIs; EarlGrey adds the synchronization engine and matcher DSL
• Maestro — Declarative mobile UI testing with YAML flows; EarlGrey provides programmatic control with Swift/Objective-C

FAQ

Q: Does EarlGrey work with SwiftUI apps? A: Yes. EarlGrey 2.0 works with SwiftUI views as long as they have accessibility identifiers set. It interacts through the same UIKit accessibility layer that SwiftUI uses.

Q: Can EarlGrey test apps on real devices? A: Yes. EarlGrey tests run on both simulators and physical devices through Xcode's standard test infrastructure.

Q: How does EarlGrey handle network synchronization? A: EarlGrey monitors NSURLSession activity and waits for pending requests to complete before executing the next test action. Custom network libraries can register as idle resources.

Q: What is the difference between EarlGrey 1 and EarlGrey 2? A: EarlGrey 2 runs the test code in a separate process from the app (like XCUITest) while maintaining in-process synchronization via eDistantObject. This allows it to work with Xcode's modern test runner.

Sources

• https://github.com/google/EarlGrey
• https://github.com/nicklama/earlgrey-tutorial