Getting Started with EarlGrey

EarlGrey is a mobile automation framework from Google that helps you write tests for your iOS applications. BrowserStack App Automate supports EarlGrey testing on a wide range of real iOS devices. This guide will help you run your first EarlGrey test on BrowserStack.

1. Setup

  1. You will need a BrowserStack username and access key. To obtain your access credentials, sign up for a free trial or purchase a plan.

  2. EarlGrey tests are the unit tests based on XCTest framework, you just need to upload your .app directory which will contain your app as well as the test-suite for the app.

Note: If you do not have an EarlGrey suite and looking to simply try EarlGrey on App Automate, you can download our Sample EarlGrey App and upload to the BrowserStack servers using the above API. Refer to our sample test repo - earlgrey-sample-browserstack

2. Upload your .app directory

You need to upload your .app directory, which contains your app as well as the test-suite for the app.

Note: If you do not have a zip file of your .app directory containing your app and test-suite, follow step by step instructions in our Build and export .app guide to generate the zip file.
-X POST ""
-F "file=@/path/to/app/file/"

Sample response for the above request is shown below:


The test_url returned in the response will be used to execute your test.


  1. App upload will take few seconds to about a minute depending on the size of your app. Do not interrupt the curl command until you get the response back.
  2. If you upload an iOS app, we will resign the app with our own provisioning profile to be able to install your app on our devices during test execution.
  3. We will delete the uploaded app after 30 days from the date of upload.

3. Execute EarlGrey test

Execute your test using the below API:

-X POST "" \
-d '{"appDir": "bs://j3c874f21852ba57957a3fdc33f47514288c4ba4", "devices": ["iPhone 8 Plus-11"]}' \
-H "Content-Type: application/json"

Sample response:

    "message" : "Success",
    "build_id" : "4d2b4deb810af077d5aed98f479bfdd2e64f36c3"

The test results are available on the command-line interface, as well as the App Automate dashboard. You have now run your first Espresso test on BrowserStack App Automate.

4. View Test Results

Once you start an Espresso test execution using REST API, you will be able to access the test execution results on the App Automate dashboard as well as using our REST API. You can access overall summary of your test execution and also check the result and debugging logs for every test case in the Espresso test-suite.

We're sorry to hear that. Please share your feedback so we can do better

Contact our Support team for immediate help while we work on improving our docs.

We're continuously improving our docs. We'd love to know what you liked

Thank you for your valuable feedback