This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

使用 TesterArmy 的 e2e

编辑页面

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


e2e 是 TesterArmy 的开源端到端(E2E)测试框架。它通过 agent-device 在 Android Emulator 或 iOS Simulator 上运行测试。一个测试可以组合两类步骤:

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

本指南介绍如何在 Expo 项目中设置 e2e,并在本地计算机上运行它。e2e 不需要 TesterArmy 账户。如果要改用 TesterArmy 托管平台运行测试,请参阅使用 TesterArmy。

验证工程简介
验证工程简介

在计算机上设置 e2e,然后使用 EAS Workflows 和 EAS Simulator 为每个 pull request 运行测试。


Prerequisites

3 requirements

1.

Node.js 22.12 或更高版本

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

2.

Android Emulator 或 iOS Simulator

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

3.

代理步骤所需的模型

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

使用 e2e 框架运行 E2E 测试

1

构建并安装发布版本

在应用配置中设置 android.package 和 ios.bundleIdentifier。e2e 使用这些值打开应用。

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

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

Terminal
# 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。稍后可以使用此路径将构建安装到新的模拟器上。

2

将 e2e 添加到项目

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

Terminal
- 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 服务器配置。

3

配置应用

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

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;

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

4

编写包含精确步骤的测试

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

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 模板中的屏幕。对于自己的应用,请将文本改为与应用屏幕匹配的内容。然后在两个平台上运行测试:

Terminal
- npx e2e run

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

5

添加代理步骤

代理步骤需要一个模型,例如先决条件中列出的订阅或提供商提供的模型。如果设置时选择了订阅或提供商,e2e.config.ts 已包含默认代理。要使用订阅,请登录并选择提供商:

Terminal
- npx e2e login

要使用 API 密钥,请设置提供商所需的环境变量。如果设置时选择了 None,请按照 e2e 模型设置将模型添加到 e2e.config.ts。要查看订阅可使用的模型 ID,请运行 npx e2e models。

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

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(); });

运行测试:

Terminal
- npx e2e run tests/agent.e2e.ts

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

6

查看结果

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

要录制每个测试的视频,请添加 --video:

Terminal
- npx e2e run --target ios --video

有关更多选项,请参阅 e2e 调试指南。

Expo 应用提示
  • 原生 tabs: Expo Router 原生 tabs报告的 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] 中打开吗?,因此测试必须处理这两种情况:
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(); } );
将 e2e 与编码代理结合使用

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

在 EAS Workflows 上运行 e2e

EAS Workflows 可以在带有 iOS Simulator 的 macOS worker 上运行 e2e。以下工作流会构建应用、在 worker 上启动模拟器、安装应用并运行测试。

1

添加 iOS Simulator 构建配置文件

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

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

2

为 worker 创建 e2e 配置

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

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;

3

创建工作流

创建 .eas/workflows/e2e-tests.yml:

.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/**/*

4

运行工作流

要启动工作流,请运行以下命令:

Terminal
- eas workflow:run .eas/workflows/e2e-tests.yml

工作流会将 .e2e/report.json 和失败文件上传到工作流运行记录的 Artifacts 部分。要在每个 pull request 上运行它,请添加 pull_request 触发器。

5

在 worker 上使用代理步骤

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

对于代理步骤:

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

在 EAS Simulator 上运行 e2e

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

1

安装 EAS Simulator 集成

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

Terminal
- npm install --save-dev @e2e-dev/eas
- yarn add --dev @e2e-dev/eas
- pnpm add --save-dev @e2e-dev/eas
- bun add --dev @e2e-dev/eas

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

Terminal
- eas init
- eas simulator:availability --json

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

该集成使用 EXPO_TOKEN 环境变量中的 Expo access token 进行身份验证,不会使用通过 eas login 登录的账户。请创建一个个人访问令牌,在运行测试时使用。

2

创建 iOS Simulator 构建

EAS 会从 EAS Build 将应用安装到远程 iOS Simulator。使用添加 iOS Simulator 构建配置文件中的 e2e-ios-simulator 配置文件创建构建:

Terminal
- eas build --platform ios --profile e2e-ios-simulator

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

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

3

为 EAS Simulator 创建 e2e 配置

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

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,因此每次运行使用一个会话。

4

运行测试

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

Terminal
- 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 文档

了解 e2e 的测试 API、模型、跟踪缓存,以及从 Maestro 和 Detox 迁移的指南。