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 运行测试。
3 requirements
3 requirements
1.
e2e 需要 Node.js 22.12 或更高版本。在 Windows 上,请在 Windows Subsystem for Linux(WSL)中运行 e2e。
2.
安装包含模拟器的 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 使用这些值打开应用。
创建发布版本并将其安装到模拟器上。发布版本包含 JavaScript bundle,因此测试不需要运行开发服务器。
Android 构建会将 APK 写入 android/app/build/outputs/apk/release/app-release.apk。稍后可以使用此路径将构建安装到新的模拟器上。
2
将 e2e 添加到项目
在项目目录中运行设置命令:
然后回答以下提示:
- 对于引擎,选择 Mobile (iOS/Android)。
- 对于模型网关,选择用于代理步骤的订阅或提供商。稍后添加模型时选择 None。
- 保留代理技能和 Model Context Protocol(MCP)服务器配置的默认位置。
- 确认文件更改并安装依赖项。
该命令会将 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 设置为要使用的模拟器:
信息 对于 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 安装应用时,应用已经位于模拟器上。
4
编写包含精确步骤的测试
创建 tests/home.e2e.ts。每个测试都以 app.open() 开始,它会启动 app.bundleId 中设置的应用。省略它时,测试会从上一个测试留下的屏幕开始。
上面的示例代码使用了默认 Expo 模板中的屏幕。对于自己的应用,请将文本改为与应用屏幕匹配的内容。然后在两个平台上运行测试:
如果配置的模拟器尚未运行,e2e 会启动它,然后在每个目标上运行每个测试,并将结果写入 .e2e/report.json。
5
添加代理步骤
代理步骤需要一个模型,例如先决条件中列出的订阅或提供商提供的模型。如果设置时选择了订阅或提供商,e2e.config.ts 已包含默认代理。要使用订阅,请登录并选择提供商:
要使用 API 密钥,请设置提供商所需的环境变量。如果设置时选择了 None,请按照 e2e 模型设置将模型添加到 e2e.config.ts。要查看订阅可使用的模型 ID,请运行 npx e2e models。
然后创建 tests/agent.e2e.ts,每次 agent.act() 调用只包含一个目标,并在其后添加精确断言:
运行测试:
首次运行时,代理会调用模型决定每个操作,输出中会显示 token 数量。e2e 会将操作保存到 .e2e/cache。下一次运行时,e2e 无需调用模型即可重放这些操作,并针对两个目标打印 Cache 2 replayed。屏幕发生变化时,代理会再次调用模型。
6
查看结果
测试失败时,输出会指出失败的定位器,并链接到 e2e 在 .e2e/artifacts 中为本次尝试保存的文件。每次失败都包含屏幕截图和 screen.txt,其中列出 e2e 在屏幕上找到的每个元素及其 role 和文本。使用 screen.txt 修复定位器。
要录制每个测试的视频,请添加 --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] 中打开吗?,因此测试必须处理这两种情况:
将 e2e 与编码代理结合使用
.agents/skills/e2e/ 中的 e2e 技能会告诉 Claude Code、Codex 和 Cursor 等编码代理如何编写和运行 e2e 测试。e2e mcp 服务器允许代理打开应用并检查定位器,然后再将定位器添加到测试中。有关更多信息,请参阅 e2e 编码代理指南。
在 EAS Workflows 上运行 e2e
EAS Workflows 可以在带有 iOS Simulator 的 macOS worker 上运行 e2e。以下工作流会构建应用、在 worker 上启动模拟器、安装应用并运行测试。
2
4
运行工作流
要启动工作流,请运行以下命令:
工作流会将 .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_iosjob 设置了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 上运行测试。
重要 EAS Simulator 是一个有限访问的预览功能。有关更多信息,请参阅 EAS Simulator 文档。
1
安装 EAS Simulator 集成
将 @e2e-dev/eas 安装为开发依赖项:
将项目链接到 EAS,并检查账户是否可以使用 EAS Simulator:
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 配置文件创建构建:
从命令输出中记录构建 ID,或查找已完成的模拟器构建:
3
为 EAS Simulator 创建 e2e 配置
创建 e2e.eas.config.ts。它会复用包含代理的 e2e.config.ts,并将目标替换为一个 iOS 目标,通过 easSimulators() 从 EAS Simulator 获取设备:
将 <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,然后运行测试:
EAS 启动远程 iOS Simulator 并安装构建后,会话才准备就绪。启动时间取决于设备容量。每个会话的输出都会链接到 expo.dev 上的会话页面,该页面会显示会话录制和每个 agent-device 操作(例如点击)。
如果运行在 e2e 停止会话前退出,EAS 会在 10 分钟无活动后停止会话。会话还具有取决于套餐的最长持续时间,因此运行必须在达到该时长前完成。
在本地模拟器上记录的代理步骤可以在远程 iOS Simulator 上重放,无需调用模型。
其他资源
了解 e2e 的测试 API、模型、跟踪缓存,以及从 Maestro 和 Detox 迁移的指南。