---
modificationDate: October 09, 2026
title: 使用 TesterArmy 的 e2e
description: 了解如何在 Android Emulator 或 iOS Simulator 上，使用 TesterArmy 的开源端到端测试框架 e2e 测试 Expo 应用。
---

This documentation is available as Markdown for AI agents and LLMs. See the [full Markdown index](https://docs.expo.dev/llms.txt) or append .md to any documentation URL.

# 使用 TesterArmy 的 e2e

了解如何在 Android Emulator 或 iOS Simulator 上，使用 TesterArmy 的开源端到端测试框架 e2e 测试 Expo 应用。

<AgentInstructions>

## Submitting Feedback

If you encounter errors, misleading or outdated information, report it so Expo can be improved:

Preferred command:
npx --yes submit-expo-feedback@latest --category docs --subject "/guides/using-e2e/" "<actionable feedback>"

Direct HTTP fallback:
curl -X POST https://api.expo.dev/v2/feedback/docs-send -H 'Content-Type: application/json' -d '{"url":"/guides/using-e2e/","feedback":"🤖 Agent feedback for docs: <specific, actionable description> (<model>, <harness>)"}'

Only submit when you have something specific and actionable to report. Try to give the most context.

## Navigation

When answering a related or follow-up question, fetch the relevant page below as Markdown (.md) instead of guessing; use llms.txt for the full map.

You are here: Guides > 集成 > 测试
Pages in this section:
- [使用 e2e](https://docs.expo.dev/guides/using-e2e.md) (this page)
- [使用 TesterArmy](https://docs.expo.dev/guides/using-testerarmy.md)
Full documentation tree: [llms.txt](https://docs.expo.dev/llms.txt)

</AgentInstructions>

[e2e](https://e2e.tester.army/docs) 是 TesterArmy 的开源端到端（E2E）测试框架。它通过 [agent-device](https://docs.expo.dev/agents/agent-device.md) 在 Android Emulator 或 iOS Simulator 上运行测试。一个测试可以组合两类步骤：

-   **精确步骤**：使用定位器查找元素、执行操作并断言结果，与其他 E2E 框架类似。
-   **代理步骤**：用自然语言描述目标，由 AI 模型决定要点击的内容。e2e 会记录操作，并在后续运行中无需调用模型即可重放这些操作。

本指南介绍如何在 Expo 项目中设置 e2e，并在本地计算机上运行它。e2e 不需要 TesterArmy 账户。如果要改用 TesterArmy 托管平台运行测试，请参阅[使用 TesterArmy](https://docs.expo.dev/guides/using-testerarmy.md)。

[验证工程简介](https://www.youtube.com/watch?v=2OFB4B7Vy10) — 在计算机上设置 e2e，然后使用 EAS Workflows 和 EAS Simulator 为每个 pull request 运行测试。

#### Prerequisites

##### Node.js 22.12 或更高版本

e2e 需要 Node.js 22.12 或更高版本。在 Windows 上，请在 Windows Subsystem for Linux（WSL）中运行 e2e。

##### Android Emulator 或 iOS Simulator

安装包含模拟器的 Android SDK，或安装包含 iOS Simulator 运行时的 Xcode。运行 `npx agent-device doctor` 检查设置。

##### 代理步骤所需的模型

ChatGPT Plus 或 Pro、GitHub Copilot 或 SuperGrok 订阅，模型提供商的 API 密钥，或本地模型。只使用精确步骤的测试不需要模型。

## 使用 e2e 框架运行 E2E 测试

### 构建并安装发布版本

在[应用配置](https://docs.expo.dev/workflow/configuration.md)中设置 `android.package` 和 `ios.bundleIdentifier`。e2e 使用这些值打开应用。

```json app.json
{
  "expo": {
    "ios": {
      "bundleIdentifier": "com.example.testerarmye2e"
    },
    "android": {
      "package": "com.example.testerarmye2e"
    }
  }
}
```

创建发布版本并将其安装到模拟器上。发布版本包含 JavaScript bundle，因此测试不需要运行开发服务器。

```sh
# Build and install on an Android Emulator
npx expo run:android --variant release

# Build and install on an iOS Simulator
npx expo run:ios --configuration Release
```

Android 构建会将 APK 写入 **android/app/build/outputs/apk/release/app-release.apk**。稍后可以使用此路径将构建安装到新的模拟器上。

### 将 e2e 添加到项目

在项目目录中运行设置命令：

```sh
npx e2e init
```

然后回答以下提示：

1.  对于引擎，选择 **Mobile (iOS/Android)**。
2.  对于模型网关，选择用于代理步骤的订阅或提供商。稍后添加模型时选择 **None**。
3.  保留代理技能和 Model Context Protocol（MCP）服务器配置的默认位置。
4.  确认文件更改并安装依赖项。

该命令会将 `e2e` 和 `@e2e-dev/mobile` 添加到开发依赖项，并将 `test:e2e` 脚本添加到 **package.json**。它还会创建以下文件：

-   **e2e.config.ts**：测试配置。
-   **tests/example.e2e.ts**：打开 iOS Settings 应用的示例测试。添加自己的测试后可以删除它。
-   **.agents/skills/e2e/**：告诉编码代理如何编写和运行 e2e 测试的技能。**.claude/skills/e2e/** 会为 Claude Code 链接到该技能。
-   **.mcp.json** 和 **.cursor/mcp.json**：供编码代理使用的 e2e MCP 服务器配置。

### 配置应用

打开 **e2e.config.ts**，为每个平台添加一个目标。将 `app.bundleId` 设置为包名或 bundle identifier，并在 `mobile()` 中将 `device` 设置为要使用的模拟器：

```ts e2e.config.ts
import type { E2EConfig } from 'e2e';
import { mobile } from '@e2e-dev/mobile';

export default {
  targets: [
    {
      name: 'ios',
      engine: mobile({
        platform: 'ios',
        device: 'iPhone 17 Pro',
      }),
      app: { bundleId: 'com.example.testerarmye2e' },
    },
    {
      name: 'android',
      engine: mobile({
        platform: 'android',
        device: 'Medium Phone',
      }),
      app: {
        bundleId: 'com.example.testerarmye2e',
        appPath: 'android/app/build/outputs/apk/release/app-release.apk',
      },
    },
  ],
  workers: 1,
} satisfies E2EConfig;
```

> **信息** 对于 Android Emulator，请使用 `npx agent-device devices` 为运行中模拟器显示的名称，例如 `Medium Phone`。带下划线的 Android Virtual Device（AVD）名称（例如 `Medium_Phone`）会在模拟器启动后失败。

`app.appPath` 指定要安装的构建。e2e 不会自动安装它。在新的模拟器上（例如 CI 机器上的模拟器），请在测试开始时调用 `await device.installApp()`，从 `app.appPath` 安装构建。使用 `npx expo run:android --variant release` 或 `npx expo run:ios --configuration Release` 安装应用时，应用已经位于模拟器上。

### 编写包含精确步骤的测试

创建 **tests/home.e2e.ts**。每个测试都以 `app.open()` 开始，它会启动 `app.bundleId` 中设置的应用。省略它时，测试会从上一个测试留下的屏幕开始。

```ts tests/home.e2e.ts
import { test } from '@e2e-dev/mobile';
import { expect } from 'e2e';

test('home screen shows the welcome title', async ({ app, screen }) => {
  await app.open();
  await expect(screen.getByText('Welcome to Expo')).toBeVisible();
});

test('explore tab expands file-based routing', async ({ app, screen }) => {
  await app.open();
  await screen.getByText('Explore').tap();
  await screen.getByText('File-based routing', { exact: false }).tap();
  await expect(screen.getByText('This app has two screens', { exact: false })).toBeVisible();
});
```

上面的示例代码使用了[默认 Expo 模板](https://docs.expo.dev/more/create-expo.md#--template)中的屏幕。对于自己的应用，请将文本改为与应用屏幕匹配的内容。然后在两个平台上运行测试：

```sh
npx e2e run
```

如果配置的模拟器尚未运行，e2e 会启动它，然后在每个目标上运行每个测试，并将结果写入 **.e2e/report.json**。

### 添加代理步骤

代理步骤需要一个模型，例如[先决条件](https://docs.expo.dev/guides/using-e2e.md#prerequisites)中列出的订阅或提供商提供的模型。如果设置时选择了订阅或提供商，**e2e.config.ts** 已包含默认代理。要使用订阅，请登录并选择提供商：

```sh
npx e2e login
```

要使用 API 密钥，请设置提供商所需的环境变量。如果设置时选择了 **None**，请按照 [e2e 模型设置](https://e2e.tester.army/docs/models)将模型添加到 **e2e.config.ts**。要查看订阅可使用的模型 ID，请运行 `npx e2e models`。

然后创建 **tests/agent.e2e.ts**，每次 `agent.act()` 调用只包含一个目标，并在其后添加精确断言：

```ts tests/agent.e2e.ts
import { test } from '@e2e-dev/mobile';
import { expect } from 'e2e';

test('agent expands file-based routing on the explore tab', async ({ agent, app, screen }) => {
  await app.open();
  await agent.act('open the Explore tab, then expand the File-based routing section');
  await expect(screen.getByText('This app has two screens', { exact: false })).toBeVisible();
});
```

运行测试：

```sh
npx e2e run tests/agent.e2e.ts
```

首次运行时，代理会调用模型决定每个操作，输出中会显示 token 数量。e2e 会将操作保存到 **.e2e/cache**。下一次运行时，e2e 无需调用模型即可重放这些操作，并针对两个目标打印 `Cache 2 replayed`。屏幕发生变化时，代理会再次调用模型。

### 查看结果

测试失败时，输出会指出失败的定位器，并链接到 e2e 在 **.e2e/artifacts** 中为本次尝试保存的文件。每次失败都包含屏幕截图和 **screen.txt**，其中列出 e2e 在屏幕上找到的每个元素及其 role 和文本。使用 **screen.txt** 修复定位器。

要录制每个测试的视频，请添加 `--video`：

```sh
npx e2e run --target ios --video
```

有关更多选项，请参阅 [e2e 调试指南](https://e2e.tester.army/docs/debugging)。

#### Expo 应用提示

-   **原生 tabs：** Expo Router [原生 tabs](https://docs.expo.dev/router/advanced/native-tabs.md)报告的 role 取决于平台和模拟器运行时。使用 `screen.getByText('Explore')` 在两个平台上查找 tab。
-   **Pressable 元素：** 没有 `accessibilityRole` 的 `Pressable` 会合并其子项的标签。例如，带箭头图标和标题的一行标签为 "Forward, File-based routing"。使用 `{ exact: false }`，或为 `Pressable` 设置 `accessibilityRole` 和 `accessibilityLabel`。
-   **文本样式：** 测试会匹配平台报告的文本。使用 `textTransform: 'uppercase'` 时，请匹配大写文本，例如 "GET STARTED"。
-   **深层链接：** `device.openLink()` 使用应用的 `scheme` 打开链接。在 iOS 上，直到该模拟器批准过一次链接，系统都会询问 `要在 [app name] 中打开吗？`，因此测试必须处理这两种情况：

#### Android

```ts tests/deep-link.e2e.ts
test(
  'deep link opens the explore screen on Android',
  { platforms: ['android'] },
  async ({ device, screen }) => {
    await device.openLink('testerarmye2eexample://explore');
    await expect(
      screen.getByText('This starter app includes example', { exact: false })
    ).toBeVisible();
  }
);
```

#### iOS

```ts tests/deep-link.e2e.ts
test(
  'deep link opens the explore screen on iOS',
  { platforms: ['ios'] },
  async ({ device, screen }) => {
    const openInApp = screen.getByRole('button', { name: 'Open' });
    const exploreIntro = screen.getByText('This starter app includes example', { exact: false });
    await device.openLink('testerarmye2eexample://explore');
    await expect
      .poll(async () => (await openInApp.count()) + (await exploreIntro.count()))
      .toBeGreaterThan(0);
    if ((await openInApp.count()) > 0) {
      await openInApp.tap();
    }
    await expect(exploreIntro).toBeVisible();
  }
);
```

#### 将 e2e 与编码代理结合使用

**.agents/skills/e2e/** 中的 e2e 技能会告诉 Claude Code、Codex 和 Cursor 等编码代理如何编写和运行 e2e 测试。`e2e mcp` 服务器允许代理打开应用并检查定位器，然后再将定位器添加到测试中。有关更多信息，请参阅 [e2e 编码代理指南](https://e2e.tester.army/docs/coding-agents)。

## 在 EAS Workflows 上运行 e2e

[EAS Workflows](https://docs.expo.dev/eas/workflows/introduction.md) 可以在带有 iOS Simulator 的 macOS worker 上运行 e2e。以下工作流会构建应用、在 worker 上启动模拟器、安装应用并运行测试。

### 添加 iOS Simulator 构建配置文件

将 iOS Simulator 构建配置文件添加到 **eas.json**：

```json eas.json
{
  "build": {
    "e2e-ios-simulator": {
      "ios": {
        "simulator": true
      }
    }
  }
}
```

### 为 worker 创建 e2e 配置

创建包含一个 iOS 目标的 **e2e.ci.config.ts**。该配置不设置 `device`，因为 worker 上只有一个已启动的模拟器：

```ts e2e.ci.config.ts
import type { E2EConfig } from 'e2e';
import { mobile } from '@e2e-dev/mobile';

export default {
  targets: [
    {
      name: 'ios',
      engine: mobile({ platform: 'ios' }),
      app: { bundleId: 'com.example.testerarmye2e' },
    },
  ],
  workers: 1,
} satisfies E2EConfig;
```

### 创建工作流

创建 **.eas/workflows/e2e-tests.yml**：

```yaml .eas/workflows/e2e-tests.yml
name: e2e tests

on:
  workflow_dispatch: {}

jobs:
  build_ios:
    name: Build iOS Simulator app
    type: build
    params:
      platform: ios
      profile: e2e-ios-simulator

  e2e_ios:
    name: Run e2e tests on iOS
    needs: [build_ios]
    runs_on: macos-medium
    environment: preview
    steps:
      - uses: eas/checkout

      - uses: eas/install_node_modules

      - uses: eas/download_build
        id: download_build
        with:
          build_id: ${{ needs.build_ios.outputs.build_id }}
          extensions: [app]

      - name: Boot a simulator and install the app
        run: |
          UDID=$(xcrun simctl list devices available --json | node -e "const d=JSON.parse(require('fs').readFileSync(0,'utf8')).devices; const all=Object.values(d).flat(); console.log(all.find(x=>x.name.startsWith('iPhone')).udid)")
          xcrun simctl boot "$UDID"
          xcrun simctl bootstatus "$UDID" -b
          xcrun simctl install "$UDID" "${{ steps.download_build.outputs.artifact_path }}"

      - name: Run e2e
        run: npx e2e run --config e2e.ci.config.ts

      - uses: eas/upload_artifact
        if: ${{ always() }}
        with:
          type: other
          name: e2e-report
          path: |
            .e2e/report.json
            .e2e/artifacts/**/*
```

### 运行工作流

要启动工作流，请运行以下命令：

```sh
eas workflow:run .eas/workflows/e2e-tests.yml
```

工作流会将 **.e2e/report.json** 和失败文件上传到工作流运行记录的 **Artifacts** 部分。要在每个 pull request 上运行它，请添加 [`pull_request`](https://docs.expo.dev/eas/workflows/syntax.md#onpull_request) 触发器。

### 在 worker 上使用代理步骤

只包含精确步骤的测试不需要模型。

对于代理步骤：

-   建议使用提供商的 API 密钥，而不是订阅登录，因为登录会在 worker 上过期。e2e 可以从 `E2E_OAUTH_CREDENTIALS` 环境变量读取订阅登录信息，该变量包含本地 **~/.config/e2e/oauth.json** 文件的内容。但 e2e 不会将刷新后的令牌写回该变量。请按照 [e2e 模型设置](https://e2e.tester.army/docs/models)，将 API 密钥对应的代理添加到 **e2e.ci.config.ts**。
-   `e2e_ios` job 设置了 `environment: preview`，因此会读取 `preview` 环境中的变量。将 API 密钥作为 [EAS 环境变量](https://docs.expo.dev/eas/environment-variables/manage.md#create-environment-variables)保存到该环境，并将可见性设置为 [Secret](https://docs.expo.dev/eas/environment-variables.md#visibility-settings-for-environment-variables)。
-   `npx e2e init` 会将 `.e2e/cache/` 添加到 **.gitignore**，因此工作流启动时没有已记录的代理步骤。要在 worker 上重放这些步骤，请删除该行并提交 **.e2e/cache** 目录。请参阅[提交跟踪记录](https://e2e.tester.army/docs/cache#commit-your-traces)。
-   重放需要屏幕上存在已记录的元素。worker 上的模拟器报告的无障碍树可能与本地模拟器不同，此时代理会调用模型。

## 在 EAS Simulator 上运行 e2e

EAS Simulator 在 EAS 基础设施上运行 Android Emulators 和 iOS Simulators。每次运行开始时，[`@e2e-dev/eas`](https://e2e.tester.army/docs/integrations/eas) 集成会为每个 e2e worker 启动一个 EAS Simulator 会话，并在运行结束时停止会话。e2e 在本地计算机上运行，并通过 agent-device 驱动每台远程设备。下面的示例会在远程 iOS Simulator 上运行测试。

> **重要** EAS Simulator 是一个有限访问的预览功能。有关更多信息，请参阅 [EAS Simulator 文档](https://docs.expo.dev/preview/eas-simulator/introduction.md)。

### 安装 EAS Simulator 集成

将 `@e2e-dev/eas` 安装为开发依赖项：

```sh
# npm
npm install --save-dev @e2e-dev/eas

# yarn
yarn add --dev @e2e-dev/eas

# pnpm
pnpm add --save-dev @e2e-dev/eas

# bun
bun add --dev @e2e-dev/eas
```

将项目链接到 EAS，并检查账户是否可以使用 EAS Simulator：

```sh
eas init
eas simulator:availability --json
```

`eas init` 会在应用配置中设置 `extra.eas.projectId`。集成使用此项目 ID 启动会话。

该集成使用 `EXPO_TOKEN` 环境变量中的 Expo access token 进行身份验证，不会使用通过 `eas login` 登录的账户。请创建一个[个人访问令牌](https://docs.expo.dev/accounts/programmatic-access.md#personal-access-tokens)，在运行测试时使用。

### 创建 iOS Simulator 构建

EAS 会从 EAS Build 将应用安装到远程 iOS Simulator。使用[添加 iOS Simulator 构建配置文件](https://docs.expo.dev/guides/using-e2e.md#add-an-ios-simulator-build-profile)中的 `e2e-ios-simulator` 配置文件创建构建：

```sh
eas build --platform ios --profile e2e-ios-simulator
```

从命令输出中记录构建 ID，或查找已完成的模拟器构建：

```sh
eas build:list --platform ios --simulator --status finished --json --non-interactive
```

### 为 EAS Simulator 创建 e2e 配置

创建 **e2e.eas.config.ts**。它会复用包含代理的 **e2e.config.ts**，并将目标替换为一个 iOS 目标，通过 `easSimulators()` 从 EAS Simulator 获取设备：

```ts e2e.eas.config.ts
import type { E2EConfig } from 'e2e';
import { mobile } from '@e2e-dev/mobile';
import { easSimulators } from '@e2e-dev/eas';

import config from './e2e.config';

export default {
  ...config,
  targets: [
    {
      name: 'ios',
      engine: mobile({
        platform: 'ios',
        device: easSimulators({
          projectId: '<your-eas-project-id>',
          buildId: process.env.IOS_SIMULATOR_BUILD_ID,
        }),
        videoTouches: false,
      }),
      app: { bundleId: 'com.example.testerarmye2e' },
    },
  ],
} satisfies E2EConfig;
```

将 `<your-eas-project-id>` 替换为应用配置中的 `extra.eas.projectId` 值。每次会话准备就绪前，EAS 都会安装并启动 `buildId` 指定的构建。

`videoTouches: false` 会关闭视频录制中的触摸指示器。在远程 iOS Simulator 上，绘制该指示器需要几分钟，因此 e2e 不会保存视频。

每个会话都会计入 EAS Simulator 用量。此配置沿用 **e2e.config.ts** 中的 `workers: 1`，因此每次运行使用一个会话。

### 运行测试

将 `<your-access-token>` 替换为个人访问令牌，将 `<build-id>` 替换为第 2 步中的构建 ID，然后运行测试：

```sh
EXPO_TOKEN=<your-access-token> IOS_SIMULATOR_BUILD_ID=<build-id> npx e2e run --config e2e.eas.config.ts
```

EAS 启动远程 iOS Simulator 并安装构建后，会话才准备就绪。启动时间取决于设备容量。每个会话的输出都会链接到 expo.dev 上的会话页面，该页面会显示会话录制和每个 agent-device 操作（例如点击）。

如果运行在 e2e 停止会话前退出，EAS 会在 10 分钟无活动后停止会话。会话还具有取决于套餐的最长持续时间，因此运行必须在达到该时长前完成。

在本地模拟器上记录的代理步骤可以在远程 iOS Simulator 上重放，无需调用模型。

## 其他资源

[e2e 文档](https://e2e.tester.army/docs) — 了解 e2e 的测试 API、模型、跟踪缓存，以及从 Maestro 和 Detox 迁移的指南。
