Getting started with EarlGrey

The mobile application user base is increasing day by day. The features in the mobile applications are added, removed and updated regularly depending on the user’s requirements. So every time there is a change in the mobile application, it needs to be tested. Manually testing all those scenarios and particularly edge cases is not feasible as it consumes a lot of time. Hence mobile automation frameworks are used to automate the test cases and that brings me to EarlGrey.It is a native testing framework developed by Google for testing iOS apps.

Setting up EarlGrey is a pretty straightforward approach. You can follow the installation steps from EarlGrey Installation Guide.

XCTest is the official testing framework provided by Apple for testing iOS applications.XCTest framework can be used to write Unit Tests. It defines the test flow of the project.setUp() and tearDown() are the commonly used methods present in XCTest Framework.

setUp() is executed before every test method and it is used to set up the initial state for all test methods.

tearDown() is executed after every test method and is used to clean up after each test method is completed.

Apple also provides an official User Interface testing framework XCUITest which is launched in 2015. It is built on top of the XCTest framework to enhance the testing of the app.

‍

EarlGrey uses the XCUITest for testing the user interactions of the app. The important features of EarlGrey include :

1. Synchronization: EarlGrey automatically synchronizes with the UI, network requests and makes sure that the UI is in a steady state before executing the tests
2. White Box Testing
3. Native Development

‍

EarlGrey tests the executed through interactions. Each test consists of

1. Selecting the element.
2. Performing an action on that selected element
3. Asserting the result of that action.

‍

The General syntax of EarlGrey tests is

EarlGrey.select(elementWithMatcher:Matcher).perform(Action).assert(Matcher)

‍

MATCHERS

‍

‍

EarlGrey provides selection API's for locating an element on the UI of the screen. The selection APIs accepts a matcher and test against all the UI element present in the screen with the provided matcher. All the matchers are present in the GREYMatcher class.EarlGrey provides users with the flexibility to select UI elements based on the specified logical conditions and also applying logical conditions helps users to uniquely select an element from the UI, such as

‍

  grey_allOf(): When this matcher is used, an AND condition is applied between all the matchers specified within this function.

‍

‍

  grey_anyOf(): Upon using this matcher, an OR condition is applied between all the matchers mentioned within this function.

‍

  grey_not(): NOT condition is applied on all the matchers present inside this function

‍

The most preferable way to select an element from the UI is to use the accessibility properties. Functions to select the element based on the accessibility properties are

1. grey_accessibilityID(): It is a string that uniquely identifies an element in the UI.

2. grey_accessibilityElement(): The UI elements that should be accessible to the users. By default, it is not accessible.

3. grey_accessibilityHint(): An accessibility hint helps users understand what happens when they perform an action on the accessibility element when that result isn't obvious from the accessibility label

4. grey_accessibilityLabel(): It is a label that identifies the UI Element.

5. grey_accessibilityTrait(): The combination of accessibility traits that best characterize the accessibility element. It helps in voice-over navigations

6. grey_accessibilityValue(): It is a string that represents the current value of the accessibility Element. For example the value of the text field.

‍

EarlGrey Accessibility Properties

‍

‍

There are other categories of matchers available such as  UI Property matchers, Hierarchy matchers, class matchers and Comparison matchers.Some of the commonly used matchers include :

• grey_notVisible(): checks that the specified UI element is not visible.
• grey_sufficientlyVisible(): checks that the specified UI element is visible.
• grey_text(): Accepts a string value and is used to locate the specified text in the UI
• grey_buttonTitle(): Accepts a string value and is used to locate the button with specified text in the UI

‍

ACTIONS

The action APIs are used to specify the action that is to be performed on the selected UI elements. All the EarlGrey actions are available in the GREYActions class. Not all actions can be performed on all the UI elements. In order to perform an action, the element must be visible on the screen. For this case, GREYMatchers comes for aid. You can use the variety of grey matcher functions to locate and uniquely identify an element on the screen and perform the action accordingly.

Some of the most commonly used EarlGrey Actions are :

1. grey_tap(): It is used to click on the UI element.
2. grey_typeText(): It is used to type the text in the Text placeholder
3. grey_clearText(): It is used to clear the value present in the placeholders
4. grey_swipeFastInDirection(): It is used to swipe fast in the specified direction
5. grey_swipeSlowInDirection(): It is used to swipe slow in the specified direction

‍

‍

The synchronization of EarlGrey is perfect most of the time but not all the time. For example, consider a scenario where you want to click an element that is not loaded in the UI hierarchy. It will cause the test to fail. Here we can have our own custom methods to wait until the UI is in our desired state before starting the test. It can be implemented as

‍

‍

ASSERTION

‍

The Assertion APIs are used to validate the result of the action performed on a UI Element. Some of the assertion methods available in EarlGrey are

• GREYAssert(expression, reason, ...): Fails if the expression evaluates to false
• GREYAssertTrue(expression, reason, ...): Fails if the expression evaluates to false. Use for BOOL expressions
• GREYAssertFalse(expression, reason, ...): Fails if the expression evaluates to true. Use for BOOL expressions
• GREYAssertNotNil(expression, reason, ...): Fails if the expression evaluates to nil
• GREYAssertNil(expression, reason, ...): Fails if the expression evaluates to a non-nil value
• GREYAssertEqual(left, right, reason, ...): Fails if left != right for scalar types
• GREYAssertNotEqual(left, right, reason, ...): Fails if left == right for scalar types
• GREYAssertEqualObjects(left, right, reason, ...): Fails if [left isEqual:right] returns false
• GREYAssertNotEqualObjects(left, right, reason, ...): Fails if [left isEqual:right] returns true
• GREYFail(reason, ...): Fails immediately with the provided reason
• GREYFailWithDetails(reason, details, ...): Fails immediately with the provided reasonable and details

‍

Custom assertions can also be done. For example, we can scroll to a particular limit, till an UI element is visible on the screen. The implementation is given below.

‍

EarlGrey FAILURE SCREENSHOTS

‍

‍EarlGrey uses a failure handler that is invoked when an exception is raised by the framework. The default handler logs the exception takes a screenshot and then prints its path along with any other useful information. You can also use GREYScreenshotUtil.takeScreenshot() and GREYScreenshotUtil.saveImage() to save the screenshot on your computer by specifying the path. Usually, the screenshots taken by EarlGrey is present in the Files folder of the simulator, You can also specify the directory where the screenshots must be saved by specifying the location in kGREYConfigKeyArtifactsDirLocation. Screenshots of the failure test give more information about the issue with the test. Hence enhancing the debugging of the cause of the Test failure.

‍‍

Conclusion

‍

This blog gives you a basic understanding of EarlGrey and the proper way to utilize the functions provided by EarlGrey in an Effective manner. You can also read in-depth about EarlGrey in the following references:

‍

• https://github.com/google/EarlGrey
• https://google.github.io/EarlGrey/
• https://chromium.googlesource.com/external/github.com/google/EarlGrey/+/refs/heads/master/docs/faq.md
• https://chromium.googlesource.com/external/github.com/google/EarlGrey/+/HEAD/Demo/EarlGreyExample/EarlGreyExampleSwiftTests/EarlGreyExampleSwiftTests.swift
• https://github.com/google/EarlGrey/blob/master/docs/cheatsheet/cheatsheet.pdf

‍