在 EAS Build 上运行 E2E 测试

初始化新项目

¥Initialize a new project

如果你已经有现有的 Expo 项目，则可以跳过此步骤。

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

使用以下命令创建一个新项目：

¥Create a new project using the following commands:

配置 EAS 构建

¥Configure EAS Build

如果你已经为项目配置了 EAS Build，则可以跳过此步骤。

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

以下命令在 Expo 服务器上为你的应用创建一个新项目，并在项目的根目录中创建 eas.json：

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

添加示例 Maestro 测试用例

¥Add example Maestro test cases

这是从默认 Expo 模板创建的应用的 UI 的样子：

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

让我们为示例应用创建两个简单的 Maestro 流程。首先在项目目录的根目录中创建一个名为 maestro 的目录。此目录将包含你将配置的流程，并且应与 eas.json 处于同一级别。

¥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.

在里面，创建一个名为 home.yaml 的新文件。此流程将启动应用并断言文本 "欢迎！" 在主屏幕上可见。

¥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!'

接下来，创建一个名为 expand_test.yaml 的新流程。此流程将在示例应用中打开 "探索" 屏幕，单击 "基于文件的路由" 可折叠项，并断言文本 "此应用有两个屏幕" 在屏幕上可见。

¥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.*'

如果你想在本地运行这些流程以验证它们是否按预期工作，你需要在本地模拟器/模拟器上安装你的应用并在终端中运行 maestro test maestro/expand_test.yaml 或 maestro test maestro/home.yaml 命令以使用 Maestro CLI 启动测试。

¥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.

创建自定义构建工作流程以运行 Maestro E2E 测试

¥Create a custom build workflow for running Maestro E2E tests

在 EAS Build 上运行 Maestro E2E 测试的最简单方法是创建 自定义构建工作流程。此工作流程将构建你的应用并在其上运行 Maestro 测试。

¥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.

首先将自定义构建配置文件添加到你的项目。在项目中与 eas.json 同级的目录 .eas/build。两个目录的路径和名称对于 EAS Build 识别项目包含自定义构建配置非常重要。

¥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.

在里面，创建一个名为 build-and-maestro-test.yml 的新配置文件。此文件定义你要运行的自定义构建工作流配置。工作流包含在自定义构建过程中执行的步骤。此自定义构建配置将执行 eas/build 自定义功能组以创建构建，然后执行 eas/maestro_test，这是一个一体化自定义功能组，用于安装 Maestro、准备测试环境（Android 模拟器或 iOS 模拟器）并使用 flow_path 输入指定的流程测试应用。

¥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

现在通过添加一个名为 build-and-maestro-test 的新 建立档案 来修改 eas.json。它将用于从 build-and-maestro-test.yml 文件运行自定义构建配置。此配置将构建应用的模拟器/模拟器版本并在其上运行 Maestro 测试。

¥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.

警告 我们观察到，如果在使用 Xcode 15.0 或 15.2 的图片上运行，Maestro 测试经常会超时。使用 latest 图片 避免任何问题。

¥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%%
}

构建你的应用并在 EAS Build 上运行 E2E 测试

¥Build your app and run E2E tests on EAS Build

要使用 build-and-maestro-test 配置文件执行自定义构建，该配置文件将构建你的应用并随后运行 Maestro E2E 测试，请运行以下命令：

¥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:

当流程失败时，任何 Maestro 工件都会自动上传为构建工件。这包括保存在 ~/.maestro/tests（默认目标）的屏幕截图。你可以从构建页面下载它们。

¥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.