Maestro in CI con GitHub Actions

Running Maestro tests locally on your machine catches bugs before you push. Running them in CI (Continuous Integration) catches bugs before they reach main and are seen by other team members. Every pull request can automatically trigger the E2E suite and block merging if any test fails.

GitHub Actions is the most popular CI platform for open-source and small-team projects. It runs workflows defined in YAML files inside .github/workflows/. An Android emulator runs inside a GitHub-hosted Linux runner, while iOS requires a macOS runner.

A GitHub Actions workflow file defines triggers (when to run), jobs (parallel or sequential work units), and steps (individual commands within a job). Each job runs on a fresh virtual machine specified by the runs-on key.

Maestro E2E tests require a running Android emulator or iOS Simulator. Android emulators run on ubuntu-latest runners. iOS Simulators require macos-latest runners, which are more expensive in GitHub Actions minutes.

The reactivecircus/android-emulator-runner GitHub Action starts an Android Virtual Device (AVD) inside the CI runner, runs your commands with the emulator available, and shuts it down after. It handles AVD creation, booting, and waiting for the device to be ready.

Choose a recent API level (api-level: 33 is Android 13) and set target: google_apis if your app uses Google Play Services or Google Maps. The emulator boot can take 2-5 minutes on GitHub's shared runners, so budget for this in your CI time estimates.

Install the Maestro CLI in the CI runner before running tests. Add the installation step to your workflow. Maestro's install script downloads the binary and adds it to the PATH.

After installation, verify the CLI is available with maestro --version. Add ~/.maestro/bin to the PATH environment variable for the rest of the workflow steps to find the binary.

Before Maestro can test the app, the APK (Android Package) must be built and installed on the emulator. Build the debug APK with Gradle and install it with adb install. For Expo apps, use EAS Build or npx expo run:android --variant release locally and commit the resulting APK as a build artifact.

To speed up CI, cache the Gradle build artifacts between runs using actions/cache. This reduces the build step from 5-10 minutes to 1-2 minutes on subsequent runs.

Run all Maestro flows with maestro test pointing to your flows directory. Use the --format flag to produce a JUnit XML report that GitHub Actions can display in the pull request UI as a test summary.

Pass environment variables from GitHub Secrets using -e KEY=${{ secrets.KEY }}. Store test account credentials in GitHub Secrets (Settings > Secrets) to keep them out of your repository code.

Use actions/upload-artifact to save the JUnit XML report and Maestro's failure screenshots as CI artifacts. These are available for download from the GitHub Actions run page for 90 days. When a test fails, download the artifacts to see exactly which screen the test was on when it failed.

Run the upload step with if: always() so it executes even when the test job fails. Without this, a failing test would prevent the artifact upload and you would have no debugging information.

The biggest time cost in a CI E2E job is usually installing Node modules, building the app, and booting the emulator. Cache node_modules between runs to skip npm install on every push. Cache the Android Gradle build to skip recompiling unchanged native code.

Use a cache key that includes a hash of your package-lock.json so the cache is invalidated when dependencies change. A well-cached job reduces from 20 minutes to under 10 minutes for most React Native projects.

iOS E2E tests require a macOS runner because iOS Simulators only run on macOS. Use runs-on: macos-latest and select the simulator with xcrun simctl. Boot the simulator before installing the app and running Maestro.

iOS CI jobs are 10x more expensive in GitHub Actions minutes than Linux jobs. Run iOS E2E only on PRs to main or on a scheduled nightly build, not on every push to feature branches.

Flaky tests — tests that sometimes pass and sometimes fail with no code changes — are a major CI reliability problem. Common causes in Maestro are: animations not finishing before assertions, slow emulator performance in CI, and network-dependent tests that fail on timeouts.

Strategies to reduce flakiness: use waitForAnimationToEnd generously, increase assertion timeouts on network-dependent steps, use clearState: true to ensure each test starts clean, and mock the backend API with a test server so responses are instant and deterministic.

Maestro Cloud (cloud.mobile.dev) is a hosted service by the Maestro team that runs your E2E tests on real devices without requiring you to manage emulators in CI. You push your app binary and flow files, and Maestro Cloud runs them on a fleet of real iOS and Android devices.

Integrate Maestro Cloud into GitHub Actions with the mobile-dev-inc/action-maestro-cloud action. It handles device provisioning, test execution, and result reporting. Real device testing catches device-specific bugs that emulators miss.

In this lesson you learned: how to write a GitHub Actions workflow that starts an Android emulator, installs Maestro, and runs E2E flows automatically on pull requests, how to cache node_modules and Gradle artifacts to speed up CI runs, and how to upload test results and failure screenshots as artifacts for post-failure debugging. Congratulations on completing the E2E Testing with Maestro course — your app now has a complete testing pyramid from unit tests through end-to-end flows.