Top Related Projects
A WebDriver server for iOS that runs inside the Simulator.
Cross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol
Calabash for iOS
Keep It Functional - An iOS Functional Testing Framework
Gray box end-to-end testing and automation framework for mobile apps
Quick Overview
EarlGrey is a native iOS UI automation test framework developed by Google. It allows developers to write clear, concise tests that interact with UI elements in iOS applications, providing a robust and reliable way to automate UI testing for iOS apps.
Pros
- Synchronization capabilities that reduce test flakiness
- Highly customizable and extensible
- Supports both Objective-C and Swift
- Integrates well with Xcode and CI/CD pipelines
Cons
- Steeper learning curve compared to some other UI testing frameworks
- Limited to iOS platform only
- May require more setup and configuration than built-in Xcode UI testing
- Performance can be slower for complex UI interactions
Code Examples
- Finding and tapping a button:
EarlGrey.selectElement(with: grey_accessibilityID("loginButton"))
.perform(grey_tap())
- Entering text into a text field:
EarlGrey.selectElement(with: grey_accessibilityID("usernameField"))
.perform(grey_typeText("testuser@example.com"))
- Verifying the presence of an element:
EarlGrey.selectElement(with: grey_text("Welcome"))
.assert(grey_sufficientlyVisible())
- Swiping on a collection view:
EarlGrey.selectElement(with: grey_accessibilityID("collectionView"))
.perform(grey_swipeFastInDirection(.left))
Getting Started
To get started with EarlGrey, follow these steps:
- Install EarlGrey using CocoaPods. Add the following to your Podfile:
target 'MyAppTests' do
pod 'EarlGrey'
end
-
Run
pod install
in your terminal. -
Import EarlGrey in your test file:
import EarlGrey
- Write your first test:
func testExample() {
EarlGrey.selectElement(with: grey_text("Hello, World!"))
.assert(grey_sufficientlyVisible())
}
- Run your tests using Xcode's Test Navigator or via the command line.
For more detailed setup instructions and advanced usage, refer to the official EarlGrey documentation.
Competitor Comparisons
A WebDriver server for iOS that runs inside the Simulator.
Pros of WebDriverAgent
- Supports multiple programming languages through WebDriver protocol
- Can be used for both iOS and web testing
- Integrates well with existing Selenium-based test suites
Cons of WebDriverAgent
- Requires more setup and configuration compared to EarlGrey
- May have slower test execution due to its client-server architecture
- Less tightly integrated with Xcode and iOS development workflow
Code Comparison
EarlGrey example:
EarlGrey.selectElement(with: grey_accessibilityID("button_id"))
.perform(grey_tap())
WebDriverAgent example:
driver.find_element_by_accessibility_id("button_id").click()
Both examples demonstrate finding and interacting with a UI element, but EarlGrey uses a more fluent, Swift-native syntax, while WebDriverAgent follows the WebDriver protocol, allowing for use with various programming languages.
Cross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol
Pros of Appium
- Cross-platform support for iOS, Android, and Windows
- Language-agnostic, allowing tests in various programming languages
- Supports both native and hybrid mobile applications
Cons of Appium
- Slower test execution compared to EarlGrey
- More complex setup and configuration process
- Less stable for iOS testing due to reliance on XCUITest
Code Comparison
EarlGrey example:
[[EarlGrey selectElementWithMatcher:grey_accessibilityLabel(@"Submit")]
performAction:grey_tap()];
Appium example:
element = driver.find_element_by_accessibility_id("Submit")
element.click()
Key Differences
- EarlGrey is specifically designed for iOS, while Appium is cross-platform
- EarlGrey offers faster test execution and better synchronization with the UI
- Appium provides more flexibility in terms of programming languages and platforms
- EarlGrey has tighter integration with Xcode and iOS development tools
- Appium has a larger community and more extensive documentation
Both tools have their strengths, with EarlGrey excelling in iOS-specific testing and Appium offering broader platform support and language flexibility.
Calabash for iOS
Pros of Calabash
- Cross-platform support (iOS and Android)
- Uses Cucumber for behavior-driven development (BDD)
- Supports natural language test scenarios
Cons of Calabash
- Slower test execution compared to EarlGrey
- Requires Ruby knowledge for test writing
- Less actively maintained than EarlGrey
Code Comparison
Calabash (Ruby):
Given /^I am on the Welcome Screen$/ do
element_exists("label marked:'Welcome'")
end
When /^I tap the "Login" button$/ do
touch("button marked:'Login'")
end
EarlGrey (Objective-C):
- (void)testLoginFlow {
[[EarlGrey selectElementWithMatcher:grey_text(@"Welcome")] assertWithMatcher:grey_sufficientlyVisible()];
[[EarlGrey selectElementWithMatcher:grey_accessibilityLabel(@"Login")] performAction:grey_tap()];
}
EarlGrey offers a more native iOS testing experience with Objective-C or Swift, while Calabash provides a cross-platform solution using Ruby and Cucumber. EarlGrey generally offers faster test execution and tighter integration with Xcode, but Calabash's BDD approach and natural language scenarios can be more accessible for non-technical team members.
Keep It Functional - An iOS Functional Testing Framework
Pros of KIF
- Simpler setup and integration process
- Uses native iOS accessibility labels, making it easier to work with existing apps
- Better support for legacy iOS versions
Cons of KIF
- Less robust synchronization mechanisms
- Limited support for custom animations and gestures
- Slower test execution compared to EarlGrey
Code Comparison
KIF example:
[tester enterText:@"user@example.com" intoViewWithAccessibilityLabel:@"Email"];
[tester enterText:@"password" intoViewWithAccessibilityLabel:@"Password"];
[tester tapViewWithAccessibilityLabel:@"Sign In"];
EarlGrey example:
[[EarlGrey selectElementWithMatcher:grey_accessibilityLabel(@"Email")]
performAction:grey_typeText(@"user@example.com")];
[[EarlGrey selectElementWithMatcher:grey_accessibilityLabel(@"Password")]
performAction:grey_typeText(@"password")];
[[EarlGrey selectElementWithMatcher:grey_accessibilityLabel(@"Sign In")]
performAction:grey_tap()];
Both frameworks use similar approaches for interacting with UI elements, but EarlGrey's syntax is more verbose and offers more granular control over actions and assertions. KIF's syntax is more concise and easier to read at a glance, but may lack some of the advanced features provided by EarlGrey.
Gray box end-to-end testing and automation framework for mobile apps
Pros of Detox
- Cross-platform support for both iOS and Android
- Faster test execution due to its gray-box approach
- Better integration with React Native projects
Cons of Detox
- Steeper learning curve for developers new to mobile testing
- Less mature ecosystem compared to EarlGrey
- Limited support for native iOS/Android components
Code Comparison
EarlGrey example:
[[EarlGrey selectElementWithMatcher:grey_accessibilityLabel(@"Submit")]
performAction:grey_tap()];
Detox example:
await element(by.label('Submit')).tap();
Both frameworks aim to simplify UI testing for mobile applications, but Detox offers a more modern, JavaScript-based approach that aligns well with React Native development. EarlGrey, being native to iOS, provides deeper integration with Apple's ecosystem but lacks cross-platform capabilities. The code examples demonstrate that Detox offers a more concise syntax, which may be more appealing to developers familiar with JavaScript and modern testing frameworks.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
Deprecation: EarlGrey 1.0 is deprecated in favor of EarlGrey 2.0 which integrates it with XCUITest. Please look at the earlgrey2 branch. EarlGrey 1.0 is not being maintained internally with iOS 13.
EarlGrey
For EarlGrey 2, please go to earlgrey2 branch.
EarlGrey is a native iOS UI automation test framework that enables you to write clear, concise tests.
With the EarlGrey framework, you have access to enhanced synchronization features. EarlGrey automatically synchronizes with the UI, network requests, and various queues; but still allows you to manually implement customized timings, if needed.
EarlGreyâs synchronization features help to ensure that the UI is in a steady state before actions are performed. This greatly increases test stability and makes tests highly repeatable.
EarlGrey works in conjunction with the XCTest framework and integrates with Xcodeâs Test Navigator so you can run tests directly from Xcode or the command line (using xcodebuild).
Getting Started
The EarlGrey documentation for users is located in the EarlGrey/docs folder. To get started, review the EarlGrey features, check for backward compatibility, and then install/run EarlGrey with your test target. After everything is configured, take a look at the EarlGrey API and start writing your own tests.
Getting Help
If you need help, several resources are available. First check the FAQ. If you have more questions after reading the FAQ, see Known Issues. You can bring more specific issues to our attention by asking them on stackoverflow.com using the #earlgrey tag. You can also start new discussions with us on our Google group or request to join our slack channel.
- FAQ - Frequently Asked Questions
- IFAQ - Infrequently Asked Questions
- Known Issues
- Stack Overflow
- Slack
- Google Group
Analytics
To prioritize and improve EarlGrey, the framework collects usage data and
uploads it to Google Analytics. More specifically, the framework collects the
MD5 hash of Bundle ID, Test Class Names and Test Method Names. This
information allows us to measure the volume of usage. For more detailed
information about our analytics collection, please peruse the
GREYAnalytics.m
file which contains the implementation details. If they wish, users can choose
to opt out by disabling the Analytics config setting in their testâs
- (void)setUp
method:
In Objective-C:
// Disable analytics.
[[GREYConfiguration sharedInstance] setValue:@(NO) forConfigKey:kGREYConfigKeyAnalyticsEnabled];
In Swift:
// Disable analytics.
GREYConfiguration.sharedInstance().setValue(false, forConfigKey: kGREYConfigKeyAnalyticsEnabled)
For Contributors
Please make sure youâve followed the guidelines in CONTRIBUTING.md before making any contributions.
Setup an EarlGrey Project
- Clone the EarlGrey repository from GitHub:
git clone https://github.com/google/EarlGrey.git
- After you have cloned the EarlGrey repository, download all the dependencies using setup-earlgrey.sh.
- After the script completes successfully, open
EarlGrey.xcodeproj
and ensure that all the targets build. - You can now use
EarlGrey.xcodeproj
to make changes to the framework.
Add and Run Tests
Unit Tests
To add unit tests for EarlGrey, use UnitTests.xcodeproj
located at
Tests/UnitTests
. To run all unit tests, select the UnitTests Scheme and press Cmd+U.
Functional Tests
To add functional tests for EarlGrey, use the FunctionalTests.xcodeproj
located
at Tests/FunctionalTests
. To run all functional tests, select the FunctionalTests Scheme and press Cmd+U.
Top Related Projects
A WebDriver server for iOS that runs inside the Simulator.
Cross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol
Calabash for iOS
Keep It Functional - An iOS Functional Testing Framework
Gray box end-to-end testing and automation framework for mobile apps
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot