Run E2E tests on EAS Build

Initialize a new project

You can skip this step if you already have an existing Expo project.

Create a new project using the following commands:

Configure EAS Build

You can skip this step if you already have EAS Build configured for your project.

The following command creates a new project on Expo servers for your app and creates eas.json in the project's root directory:

Add example Maestro test cases

This is what the UI of the app created from the default Expo template looks like:

Let's create two simple Maestro flows for the example app. Start by creating a directory called maestro in the root of your project directory. This directory will contain the flows that you will configure and should be at the same level as eas.json.

Inside, create a new file called home.yaml. This flow will launch the app and assert that the text "Welcome!" is visible on the home screen.

appId: dev.expo.eastestsexample # This is an example app id. Replace it with your app id.
---
- launchApp
- assertVisible: 'Welcome!'

Next, create a new flow called expand_test.yaml. This flow will open the "Explore" screen in the example app, click on the "File-based routing" collapsible, and assert that the text "This app has two screens" is visible on the screen.

appId: dev.expo.eastestsexample # This is an example app id. Replace it with your app id.
---
- launchApp
- tapOn: 'Explore.*'
- tapOn: '.*File-based routing'
- assertVisible: 'This app has two screens.*'

If you want to run these flows locally to verify that they work as expected, you need to install your app on your local simulator/emulator and run maestro test maestro/expand_test.yaml or maestro test maestro/home.yaml commands in the terminal to use Maestro CLI to start the tests.

Create a custom build workflow for running Maestro E2E tests

The easiest way to run Maestro E2E tests on EAS Build is to create a custom build workflow. This workflow will build your app and run the Maestro tests on it.

Start by adding a custom build config file to your project. Create a directory .eas/build at the same level as eas.json in the project. The path and the name of both directories are important for EAS Build to identify that a project contains a custom build config.

Inside, create a new config file called build-and-maestro-test.yml. This file defines the custom build workflow config that you want to run. Workflow contains steps that are executed during the custom build process. This custom build config will execute the eas/build custom function group to create a build and then the eas/maestro_test which is an all-in-one custom function group that installs Maestro, prepares a testing environment (Android Emulator or iOS Simulator) and tests the app using flows specified by the flow_path input.

build:
  name: Create a build and run Maestro tests on it
  steps:
    - eas/build
    - eas/maestro_test:
        inputs:
          flow_path: |
            maestro/home.yaml
            maestro/expand_test.yaml

Now modify the eas.json by adding a new build profile called build-and-maestro-test. It will be used to run the custom build config from the build-and-maestro-test.yml file. This configuration will build the emulator/simulator version of your app and run the Maestro tests on it.

We have observed that Maestro tests often time out if run on images with Xcode 15.0 or 15.2. Use the latest image to avoid any issues.

{
  "build": {
    %%placeholder-start%%... %%placeholder-end%%
    "build-and-maestro-test": {
      "withoutCredentials": true,
      "config": "build-and-maestro-test.yml",
      "android": {
        "buildType": "apk",
        "image": "latest"
      },
      "ios": {
        "simulator": true,
        "image": "latest"
      }
    }
  }
  %%placeholder-start%%... %%placeholder-end%%
}

Build your app and run E2E tests on EAS Build

To execute a custom build using the build-and-maestro-test profile that will build your app and run the Maestro E2E tests afterward, run the following command:

When the flow fails, any Maestro artifacts are automatically uploaded as build artifacts. This includes screenshots saved at ~/.maestro/tests (the default destination). You can download them from the build page.