EarlGrey Documentation

EarlGrey simulates real user behavior by performing taps and swipes using app-level touch events rather than element-level event handlers.

Before every UI interaction, EarlGrey automatically asserts that the target elements are visible (via screenshot diffs) and not just present in the view hierarchy. This helps identify bugs that would affect actual users.

EarlGrey automatically synchronizes with the UI, network requests, main Dispatch Queue, and the main NSOperationQueue to ensure the app is idle before performing actions or assertions.

EarlGrey synchronizes with the following resources:

• App Resource
• Main Dispatch Queues
• Main NSOperationQueue
• Animations
• Gestures
• Network
• View Controller Appearance / Disappearance
• Keyboard Typing
• Scrolling
• Main Run Loop
• Web View

If you need to wait for specific events that are not covered by automatic synchronization, use EarlGrey's Synchronization APIs to control behavior and increase test stability.

EarlGrey uses screenshot differential comparison (screenshot diffs) to determine if UI elements are visible before interacting with them. This ensures that interactions only occur on elements a real user can actually see.

Note: System-generated alert views or other out-of-process modal dialogs that obscure the UI may interfere with visibility checks.

The EarlGreyContribs project contains two specific test targets used for testing experimental APIs:

• EarlGreyContribsTests (Objective-C/C++)
• EarlGreyContribsSwiftTests (Swift)

When adding or testing a new experimental API, you should replicate the implementation in both targets to ensure coverage across both languages.

If you do not have a working Ruby installation, you can set up Ruby using rbenv. This process involves installing rbenv via Homebrew, configuring your shell profile (~/.bash_profile or ~/.zshrc), and installing specific Ruby gems including bundler, fastlane, and cocoapods.

# 1. Install rbenv
brew update
brew install rbenv

# 2. Add to ~/.bash_profile or ~/.zshrc
export PATH="$HOME/.rbenv/bin:$PATH"
eval "$(rbenv init -)"

# 3. Source your profile
source ~/.bash_profile
# OR
source ~/.zshrc

# 4. Install Ruby and required gems
rbenv install 2.4.0
rbenv global 2.4.0
echo "gem: --no-document" >> ~/.gemrc
gem update --system --no-document
gem install --no-document bundler fastlane cocoapods

# 5. Initialize
rbenv init

React Native elements are accessible to EarlGrey if they have the appropriate accessibility props.

• Use grey_accessibilityLabel to match elements with the accessibilityLabel prop.
• Use grey_accessibilityID to match elements with the testID prop (this works even if accessible: false is set).

Mapping Reference:

Deprecation Warning

EarlGrey 1.0 is deprecated and is not being maintained internally for iOS 13.

If you are starting a new project or need support for newer iOS versions, you should use EarlGrey 2.0, which integrates with XCUITest. You can find the EarlGrey 2.0 source in the earlgrey2 branch.

Use the earlggrey install command to automatically install EarlGrey into an Xcode unit test target. This tool supports Carthage, CocoaPods, and Swift integration.

Before running the install command, ensure you have:

1. Created a new target of type iOS Unit Testing Bundle.
2. Created a new scheme for that target via Product → Scheme → Manage Schemes and marked it as shared.

1. Set up a test target: Follow the same steps as the CocoaPods installation to create an iOS Unit Testing Bundle.
2. Configure Carthage:
   • Install Carthage via Homebrew: brew install carthage.
   • Add EarlGrey to Cartfile.private (e.g., github "google/EarlGrey" "1.16.0").
   • Update dependencies: carthage update EarlGrey --platform ios.
3. Use the EarlGrey gem:
   • Install the gem: gem install earlgrey.
   • Install EarlGrey into your specific testing target: earlgrey install -t <YOUR_TEST_TARGET_NAME>.
   • For more options, run earlgrey help install.

brew update
brew install carthage
echo 'github "google/EarlGrey" "1.16.0"' >> Cartfile.private
carthage update EarlGrey --platform ios
gem install earlgrey
earlgrey install -t EarlGreyExampleSwiftTests

To ensure a clean state, implement a resetApplicationForTesting() method on your AppDelegate. In your test target's setUp() method, acquire the app delegate and call this reset method.

Note: Ensure Defines Module is set to Yes in your application target's Build Settings. In Swift, use @testable import to access the app module.

// Swift: Resetting state in setUp
@testable import App

class MyTests: XCTestCase {
    override func setUp() {
        super.setUp()
        let appDelegate: AppDelegate = UIApplication.shared.delegate as! AppDelegate
        appDelegate.resetApplicationForTesting()
    }
}

To contribute to EarlGrey or build the framework from source, follow these steps:

1. Clone the repository: git clone https://github.com/google/EarlGrey.git
2. Download dependencies using the provided script: ./Scripts/setup-earlgrey.sh
3. Open EarlGrey.xcodeproj and verify that all targets build successfully.