Getting Started with EarlGrey: iOS UI Testing Framework Installation and First Test Case

EarlGrey is Google’s open‑source functional UI testing framework for iOS, used by apps such as YouTube, Google Calendar, and Google Photos. It works alongside XCTest and integrates into Xcode’s Test Navigator, allowing tests to be run directly from Xcode or the command line.

Key Features include real‑device test execution, a powerful built‑in synchronization mechanism that keeps UI, network requests, and queries stable, visibility checks that ensure interactions only occur on visible elements, and a flexible, extensible design for matchers, actions, and assertions.

Environment Preparation requires Xcode (downloadable from Apple) and CocoaPods for dependency management. CocoaPods is a Ruby‑based tool that creates a workspace and resolves third‑party library dependencies.

Installing CocoaPods can be done with the following commands (run in a terminal): sudo gem install cocoapods If the default source is blocked, replace it with the Taobao mirror:

pod repo remove master

pod repo add master https://mirrors.tuna.tsinghua.edu.cn/git/CocoaPods/Specs.git

After installation, verify the source with: pod repo list Installing EarlGrey via CocoaPods adds EarlGrey to the Podfile. For CocoaPods 0.39.0 use: pod 'EarlGrey', :path => 'EarlGrey' For CocoaPods 1.0.0 use the same syntax. Run the installation with: pod install --verbose --no-repo-update Manual Installation involves downloading the source archive from GitHub (e.g., https://github.com/google/EarlGrey/archive/1.0.0.zip), extracting it, and adding EarlGrey.xcodeproj to the app’s Xcode project. Then link EarlGrey.framework in the test target’s Build Phases, add the appropriate Header and Framework Search Paths, disable Bitcode, and set the environment variable

DYLD_INSERT_LIBRARIES=@executable_path/EarlGrey.framework/EarlGrey

in the test scheme.

First Test Case creation steps: create a new Unit Test Case class (not a UI Test Case), ensure the test target is selected, delete the template code, and add a simple assertion such as checking that the key window is visible. Run the test from the Test Navigator.

Official Example Cases (both Objective‑C and Swift) illustrate element matching, actions, error handling, custom matchers, searching off‑screen elements, custom assertions, and waiting with GREYCondition. They demonstrate the separation of element selection and interaction in the EarlGrey API.

Comparison with Other iOS Automation Frameworks is provided in a visual table (not reproduced here).

Troubleshooting includes common issues such as download failures due to GFW blocking (use a VPN or alternative mirrors), outdated Ruby gems (upgrade with gem update --system), and pod install errors (ensure correct scheme and environment variable settings).