This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.
Run E2E tests on Expo Workflows with Maestro
Edit page
Learn how to set up and run E2E tests on Expo Workflows with Maestro.
Run E2E tests with an AI agent
Paste this into Claude, Cursor, Codex, or another agent.
Set up and run E2E tests with Maestro on Expo Workflows. Use https://docs.expo.dev/eas/workflows/examples/e2e-tests.md as the source for each command and file. 1. Check that EAS CLI is installed and up to date. If it is not, run `npm install -g eas-cli`. 2. Check that I am logged in with `eas whoami`. If I am not, stop and ask me to run `eas login` or to set `EXPO_TOKEN`. Do not print a token. 3. If the project does not have an Expo Services project ID, ask me before you run `eas init`. 4. Ask me which platforms to test: Android, iOS, or both. 5. Read the screens of my app. Write two or more Maestro flows in the .maestro directory that launch the app and check text that my app shows. The flows on the page match only the default Expo template. Set `appId` in each flow to `android.package` or `ios.bundleIdentifier` from the app config. If the value is not set, ask me for it. If I test both platforms and the two values are different, ask me how to continue. 6. Add the `e2e-test` build profile from the page to eas.json. Create eas.json if it does not exist. Do not change the other profiles. 7. For each platform, write the workflow from the page to .eas/workflows/e2e-test-android.yml or .eas/workflows/e2e-test-ios.yml. Put the paths of my flows in `flow_path`. 8. For each workflow, run `eas workflow:run .eas/workflows/<file name> --non-interactive --wait --json`. 9. If a run fails, find the failed job in the JSON output, run `eas workflow:logs <job ID> --non-interactive`, and tell me which job failed and why. If a Maestro flow fails, tell me which step failed and suggest a change to the flow. Do not change my app code without asking me. 10. Give me the workflow run links from the command output. Tell me which files you changed and which commands you ran. 11. Tell me that the workflows run on each pull request only when my GitHub repository is linked to the project in the Expo dashboard.
In this guide, you'll learn how to run end-to-end (E2E) tests on Expo Workflows using Maestro. The example demonstrates how to configure your E2E tests workflow using the default Expo template. For your own app, you'll need to adjust the flows to match your app's UI.
1
Set up your project
If you haven't already, create a new project and sync it with Expo Services.
Follow the Get started with Expo Workflows guide to create a new project and sync it with Expo Services. Then, configure your project and link your GitHub repository.
2
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 you'll configure and should be at the same level as eas.json.
Inside, create a new file called home.yml. This flow will launch the app and assert that the text "Welcome!" is visible on the home screen.
Next, create a new flow called expand_test.yml. 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.
3
Run Maestro tests locally (optional)
To run Maestro tests locally, install the Maestro CLI by following the instructions in Installing Maestro.
Install your app on a local Android Emulator or iOS Simulator. Open a terminal, navigate to the Maestro directory, and run the following commands to start the tests with the Maestro CLI:
The video below shows a successful run of the .maestro/expand_test.yml flow:
4
Build profile for E2E tests
E2E tests require a built app file: .apk for Android or .app for iOS — that Expo Workflows can install and test on an emulator/simulator.
In your eas.json file, create a build profile for E2E tests. If the file doesn't exist, run eas build:configure to generate it.
The above build profile creates an .apk for Android and an .app for iOS. The workflow uses this profile to build the app on Expo servers.
5
Create an E2E test workflow
At the root of your project, create an .eas/workflows directory. Then, add a YAML file for your E2E test workflow, such as .eas/workflows/e2e-test-android.yml.
This workflow builds an .apk for Android using the e2e-test build profile from the previous step. Then it runs the .maestro/home.yml flow on the built APK.
Here's an example of the same test workflow for iOS:
Learn more about Syntax for Expo Workflows.
6
Run the E2E test workflow
You can run the E2E test workflow in two ways:
- Manually using the EAS CLI
- Automatically when you open a pull request
The workflow uses a pull_request trigger to run automatically when someone opens a pull request to your repository. Learn more about Expo Workflows triggers.
After the workflow starts, you can track its progress and view the results in the Expo dashboard. Here's a screenshot of a completed workflow run:
More
Learn more about the syntax for Expo Workflows.
Learn more about example CI/CD workflows for Expo Workflows.
Track pass, flake, and failure trends for your Maestro tests over time.
Learn more about Maestro flows and how to write them.