EarlGrey 2 —Direct Project Copy Setup Guide

Szymon Kazmierczak
Dec 13, 2019 · 3 min read

This post is part of a group of articles aimed at helping you set up & get started with EarlGrey 2.

This post covers the set up of EarlGrey 2 in your project, using a direct project copy. Both video and written setup are provided!

EarlGrey 2 Setup Guide Video

I. Copy EarlGrey2

1. Clone Earlgrey 2 repository into your project — make sure to clone the earlgrey2 branch!

2. Download earlgrey2's dependencies.
Tip: To do that, in the terminal, navigate to the EarlGrey2 directory, then run the following shell script:

Make sure that after this step, your folder structure is as follows:

II. Add EarlGrey2 to your project

1. Open Earlgrey xcode project and make sure that both AppFramework and TestLib build.

2. Add the EarlGrey.xcodeproj file to your project’s Xcode.
Tip: To do this, drag the earlgrey.xcodeproj file from the EarlGrey directory to your project. Make sure that the project is added under your project — otherwise xcode will ask you to create a workspace and you don’t want that.

III. Add an EarlGrey2 UI Testing Target

  1. Create a UI Testing Target if you don’t already have one!
  2. Open your UI Testing Target, and in , add into the “link with libraries” section.
    Tip: When you press the + button, you should be able to find it by using the search bar — It should show up under the EarlGrey project.
  3. In , add to .
  4. Add the location of EarlGrey and eDistantObject to your
    Tip: If you followed the step number 3, these directories should be under

5. Add AppFramework — in , create a by pressing the + button in top left of build phases.

Destination: `Absolute Path`
Path: $(TARGET_BUILD_DIR)/../../YOUR_APP.app/Frameworks
Note: make sure to replace YOUR_APP with the name of your app!
— unchecked!
Press the + button and add AppFramework.framework it should show up under EarlGrey.xcodeproj Products.

IV. Swift Support

Few changes have to be made to make EarlGrey2 usable in Swift.

  1. Add EarlGrey.swift wrapper.
    Tip: You can download the file from the repository here — https://github.com/google/EarlGrey/blob/earlgrey2/TestLib/Swift/EarlGrey.swift
  2. Add bridging header to make sure EarlGrey.swift compiles.
    Tip: Add a new header file, and paste the following code into it to make sure your EarlGrey.swift compiles.
#import “AppFramework/Action/GREYAction.h”
#import “AppFramework/Action/GREYActionBlock.h”
#import “AppFramework/Action/GREYActions.h”
#import “CommonLib/DistantObject/GREYHostApplicationDistantObject.h”
#import “CommonLib/Matcher/GREYElementMatcherBlock.h”
#import “CommonLib/Matcher/GREYMatcher.h”
#import “TestLib/AlertHandling/XCTestCase+GREYSystemAlertHandler.h”
#import “TestLib/EarlGreyImpl/EarlGrey.h”

Now in of your UI Target, add the bridging header to the .
Now you should be able to build without errors now!

V. Write your first test to verify EarlGrey2 Integration

In your UI Test target, create a new test with the following:

func testExample() {
let application: XCUIApplication = XCUIApplication()
EarlGrey.selectElement(with: grey_keyWindow())

Now run it — if everything was set up correctly, it should pass and your black-box version of EarlGrey2 is now set up!

For a sample project, head over to my GitHub — Black-box EarlGrey2 Integration

If you’re interested in a cocoapods setup, have a look here — Black-box EarlGrey2 Cocoapods Integration

Common Issues:
- -eDistantObject not resolved — make sure you downloaded EarlGrey2’s dependencies see I. , step 2.
- Unable to compile, missing header files — make sure your the header files can be found by adjusting your User Header Search Paths in your UI Testing target.


Best practices, quality assurance, software engineering, career and more

Szymon Kazmierczak

Written by

Software Development Engineer in Test


Best practices, quality assurance, software engineering, career and more

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade