React Native Academy · 课时

使用 GitHub Actions 在持续集成中运行 Maestro

将 Maestro 测试任务添加到 GitHub Actions 工作流，在持续集成环境中启动 Android 模拟器，运行 Maestro 测试套件，并在失败时上传结果文件。

使用 GitHub Actions 在持续集成中运行 Maestro 是 CoddyKit 上的免费 React Native Academy 课时。这是第 4 节课，共 4 节。你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。这是 React Native Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 React Native Academy 课程共包含 4 节课。

本课时的部分内容尚未翻译，以英文显示。

Why Run Maestro in CI?

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.

GitHub Actions Workflow Basics

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.

# .github/workflows/e2e.yml
name: E2E Tests

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  e2e-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run Maestro E2E Tests
        run: echo 'Steps to follow...'

Starting an Android Emulator in CI

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.

jobs:
  e2e-android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Java
        uses: actions/setup-java@v4
        with:
          java-version: '17'
          distribution: 'temurin'

      - name: Enable KVM (hardware acceleration)
        run: |
          echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
          sudo udevadm control --reload-rules
          sudo udevadm trigger --name-match=kvm

      - name: Run Android Emulator
        uses: reactivecircus/android-emulator-runner@v2
        with:
          api-level: 33
          arch: x86_64
          script: echo 'Emulator is ready'

Installing Maestro in CI

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.

      - name: Install Maestro CLI
        run: |
          curl -Ls 'https://get.maestro.mobile.dev' | bash
          echo '$HOME/.maestro/bin' >> $GITHUB_PATH

      - name: Verify Maestro installation
        run: maestro --version

Building and Installing the APK

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.

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Build Debug APK
        run: cd android && ./gradlew assembleDebug

      - name: Install APK on emulator
        run: adb install android/app/build/outputs/apk/debug/app-debug.apk

Running the Maestro Test Suite

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.

      - name: Run Maestro E2E Tests
        env:
          TEST_EMAIL: ${{ secrets.E2E_TEST_EMAIL }}
          TEST_PASSWORD: ${{ secrets.E2E_TEST_PASSWORD }}
        run: |
          maestro test \
            -e TEST_EMAIL=$TEST_EMAIL \
            -e TEST_PASSWORD=$TEST_PASSWORD \
            --format junit \
            --output test-results.xml \
            maestro/flows/

Uploading Test Results and Screenshots

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.

      - name: Upload test results
        if: always()  # Upload even if tests fail
        uses: actions/upload-artifact@v4
        with:
          name: e2e-test-results
          path: |
            test-results.xml
            ~/.maestro/tests/
          retention-days: 30

      - name: Publish Test Report
        if: always()
        uses: mikepenz/action-junit-report@v4
        with:
          report_paths: 'test-results.xml'
          check_name: 'E2E Test Results'

Caching Dependencies for Speed

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.

      - name: Cache Node modules
        uses: actions/cache@v4
        with:
          path: node_modules
          key: node-${{ hashFiles('package-lock.json') }}
          restore-keys: node-

      - name: Cache Gradle
        uses: actions/cache@v4
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
            android/.gradle
          key: gradle-${{ hashFiles('**/*.gradle*', '**/gradle-wrapper.properties') }}
          restore-keys: gradle-

Running Maestro on iOS in CI

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.

  e2e-ios:
    runs-on: macos-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start iOS Simulator
        run: |
          xcrun simctl boot 'iPhone 16'
          open -a Simulator

      - name: Install dependencies
        run: npm ci

      - name: Build iOS app
        run: npx expo run:ios --configuration Release --no-bundler

      - name: Install Maestro
        run: curl -Ls 'https://get.maestro.mobile.dev' | bash && echo '$HOME/.maestro/bin' >> $GITHUB_PATH

      - name: Run E2E Tests
        run: maestro test maestro/flows/ --format junit --output ios-results.xml

Handling Flaky Tests in CI

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.

# Add retry logic at the workflow level for flaky suites
      - name: Run Maestro (with retry)
        uses: nick-fields/retry@v3
        with:
          timeout_minutes: 15
          max_attempts: 2
          command: |
            maestro test \
              --format junit \
              --output test-results.xml \
              maestro/flows/

Integrating with Maestro Cloud

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.

      - name: Upload to Maestro Cloud
        uses: mobile-dev-inc/action-maestro-cloud@v1
        with:
          api-key: ${{ secrets.MAESTRO_CLOUD_API_KEY }}
          app-file: android/app/build/outputs/apk/debug/app-debug.apk
          workspace: maestro/flows/
          env: |
            TEST_EMAIL=${{ secrets.E2E_TEST_EMAIL }}
            TEST_PASSWORD=${{ secrets.E2E_TEST_PASSWORD }}

Quick Check

Test your understanding of React Native Mobile Development concepts from this lesson.

Lesson Recap

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.

常见问题解答

「使用 GitHub Actions 在持续集成中运行 Maestro」课时是免费的吗？

是的 — 「使用 GitHub Actions 在持续集成中运行 Maestro」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 React Native Academy 课程的其余内容，请升级到 CoddyKit PRO。 React Native Academy 课程共包含 4 节课。

「使用 GitHub Actions 在持续集成中运行 Maestro」这节课中我会学到什么？

将 Maestro 测试任务添加到 GitHub Actions 工作流，在持续集成环境中启动 Android 模拟器，运行 Maestro 测试套件，并在失败时上传结果文件。你通过在浏览器中直接运行的动手代码来练习 React Native Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。

学习 React Native Academy 需要有经验吗？

无需任何先前经验。CoddyKit 上的 React Native Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。这是第 4 节课，共 4 节。

「使用 GitHub Actions 在持续集成中运行 Maestro」课时需要多长时间？

大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。

我能在这节 React Native Academy 课中编写并运行代码吗？

能。每节 React Native Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。

此课程中的所有课时

← 返回 React Native Academy