Convert Figma logo to code with AI

google logoEarlGrey

:tea: iOS UI Automation Test Framework

5,610
740
5,610
233

Top Related Projects

A WebDriver server for iOS that runs inside the Simulator.

18,634

Cross-platform automation framework for all kinds of apps, built on top of the W3C WebDriver protocol

Calabash for iOS

6,206

Keep It Functional - An iOS Functional Testing Framework

11,134

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

  1. Finding and tapping a button:
EarlGrey.selectElement(with: grey_accessibilityID("loginButton"))
    .perform(grey_tap())
  1. Entering text into a text field:
EarlGrey.selectElement(with: grey_accessibilityID("usernameField"))
    .perform(grey_typeText("testuser@example.com"))
  1. Verifying the presence of an element:
EarlGrey.selectElement(with: grey_text("Welcome"))
    .assert(grey_sufficientlyVisible())
  1. 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:

  1. Install EarlGrey using CocoaPods. Add the following to your Podfile:
target 'MyAppTests' do
  pod 'EarlGrey'
end
  1. Run pod install in your terminal.

  2. Import EarlGrey in your test file:

import EarlGrey
  1. Write your first test:
func testExample() {
  EarlGrey.selectElement(with: grey_text("Hello, World!"))
      .assert(grey_sufficientlyVisible())
}
  1. 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.

18,634

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.

6,206

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.

11,134

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 Figma logo designs to code with AI

Visual Copilot

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

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

Apache License CC-BY 4.0 License Build Status Carthage compatible CocoaPods Gem Version

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.

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

  1. Clone the EarlGrey repository from GitHub:
git clone https://github.com/google/EarlGrey.git
  1. After you have cloned the EarlGrey repository, download all the dependencies using setup-earlgrey.sh.
  2. After the script completes successfully, open EarlGrey.xcodeproj and ensure that all the targets build.
  3. 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.