expo-testing

Expo 测试

在 iOS 模拟器和实体设备上构建、安装和测试 Expo/React Native 应用。

检测项目配置

开始任何操作前，读取项目配置以确定：

1. Bundle ID — 从 app.config.js、app.config.ts 或 app.json 中读取 → expo.ios.bundleIdentifier
2. EAS 配置文件 — 从 eas.json 中读取 → 可用的构建配置文件（development、preview、production）
3. Detox 配置 — 从 .detoxrc.js 或 detox.config.js 中读取 → 测试运行程序、构建命令、设备配置
4. 深层链接 scheme — 从 app.config.js 中读取 → expo.scheme
5. 包管理器 — bun.lockb → bun，pnpm-lock.yaml → pnpm，yarn.lock → yarn，否则使用 npm

两种路径

路径 1：模拟器（默认）

用于自动化测试、TDD 循环和无人值守运行。

1. Prebuild (if native code changed)
   npx expo prebuild --platform ios --clean

2. Build for simulator
   xcodebuild -workspace ios/<AppName>.xcworkspace \
     -scheme <AppName> \
     -configuration Debug \
     -sdk iphonesimulator \
     -derivedDataPath ios/build

3. Install on booted simulator
   xcrun simctl install booted ios/build/Build/Products/Debug-iphonesimulator/<AppName>.app

4. Launch
   xcrun simctl launch booted <bundleId>

自动检测是否需要重新构建：检查自上次构建后以下内容是否有变化：

• ios/ 目录内容（原生模块）
• package.json 或锁文件（新增原生依赖）
• app.config.js / app.json（配置变更）
• 任何匹配 *.podspec 或 Podfile 的文件

如果以上内容均未变化，则跳过预构建和 xcodebuild — 只需重新安装并启动。

路径 2：实体设备

用于手动测试、与他人分享或测试特定硬件功能。

本地（通过 USB 连接）：

npx expo run:ios --device

列出已连接的设备并直接安装。

EAS 云构建（可分享）：

1. Build
   eas build --profile preview --platform ios

2. Download and install
   # EAS provides a QR code / install link
   # Or download .ipa and install via Finder/Apple Configurator

设备注册（仅首次需要）：

eas device:create
# Follow the URL to register the device's UDID

运行 Detox 测试

在模拟器上完成构建和安装后：

# Full suite
npx detox test --configuration ios.sim.debug

# Specific test file
npx detox test --configuration ios.sim.debug e2e/<testFile>.e2e.ts

# With screenshots on failure (default Detox behavior)
# Artifacts saved to artifacts/ directory

运行 Detox 前，检查是否需要重新构建 Detox 二进制文件：

npx detox build --configuration ios.sim.debug --if-missing

如果二进制文件已存在且为最新版本，则会跳过构建。

E2E 最佳实践

• 在交互元素上使用 testID 属性，以便可靠地定位元素
• 对包含动画或计时器的屏幕，禁用 Detox 同步：

  await device.disableSynchronization();
  // interact with animated screen
  await device.enableSynchronization();
  

• 使用深层链接作为测试入口：如果应用配置了 URL scheme（应用配置中的 expo.scheme），可以直接启动到指定屏幕：

  await device.openURL({ url: '<scheme>://e2e' });
  

  如果没有 scheme，但需要 E2E 测试入口，可以考虑添加一个 — 这样测试就能跳过引导流程，直接进入待测屏幕。

截图

为了试用自家产品和发现 Bug，请截取屏幕截图：

// In Detox tests
await device.takeScreenshot('descriptive-name');

截图会保存到 Detox artifacts 目录（可在 .detoxrc.js 中配置）。请确保将 artifacts 目录添加到 .gitignore。

在模拟器上手动截取屏幕截图：

xcrun simctl io booted screenshot screenshots/<name>.png

将试用自家产品时生成的 artifacts 存放在 .dogfooding/（已添加到 gitignore）：

.dogfooding/
  screenshots/
  findings.md
  logs/

失败时的 artifacts

测试失败时，请保留所有有助于调试的内容：

• 屏幕截图 — Detox 会在失败时自动截取
• 设备日志 — xcrun simctl spawn booted log stream --level error
• 控制台输出 — 来自测试运行程序
• Sentry — 如果已配置 Sentry，请检查崩溃报告

并行模拟器隔离

夜间运行多个都需要使用模拟器的 swarm/Agent 时，每个都必须使用各自的：

# Create a named simulator for this agent
xcrun simctl create "Swarm-1" "iPhone 16"
# Returns a UDID like: 4A2B3C4D-5E6F-7890-ABCD-EF1234567890

# Boot it
xcrun simctl boot <UDID>

# Build and install targeting that specific simulator
xcrun simctl install <UDID> ios/build/Build/Products/Debug-iphonesimulator/<AppName>.app
xcrun simctl launch <UDID> <bundleId>

对于 Detox，在 .detoxrc.js 中按名称指定目标设备：

devices: {
  simulator: {
    type: 'ios.simulator',
    device: { type: 'iPhone 16', name: 'Swarm-1' }
  }
}

运行后清理：

xcrun simctl delete <UDID>

故障排除

问题	解决方法
No bundle URL present	先在另一个终端运行 npx expo start
添加包后构建失败	运行 npx expo prebuild --platform ios --clean，然后重新构建
找不到模拟器	运行 xcrun simctl list devices available 查找已启动的设备
Detox 超时	在 .detoxrc.js 中增加超时时间，并检查是否缺少 testID
EAS 构建队列缓慢	模拟器测试使用本地构建，设备分享使用 EAS
xcrun simctl install 失败	检查 .app 路径 — Debug 还是 Release、模拟器还是设备

注意事项

• Detox 需要开发构建，而不是 Expo Go。 Expo Go 不支持 Detox 所需的原生模块或自定义开发客户端配置。进行 Detox 测试时，务必使用 npx expo prebuild + xcodebuild。
• iPad 与 iPhone 模拟器的尺寸差异很重要。 在 iPhone 上通过的 Detox 测试，可能会因布局不同（分屏视图、更大的屏幕）而在 iPad 上失败。务必使用与生产环境目标设备相同类型的模拟器进行测试。
• EAS 构建很慢——尽早触发。 云端构建可能需要 10-20 分钟。请并行触发 EAS 构建并开展其他工作，不要先等待 CI 完成。
• EAS 的二维码会过期。 如果你在 PR 中分享预览构建的二维码，构建产物清理后二维码就会过期。如果构建已超过几天，请发布新的二维码。
• npx expo run:ios --device 需要连接设备。 设备必须通过 USB 实际连接并设为可信设备。初次安装时，无线调试并不可靠。
• 如果没有运行中的模拟器，Detox 测试即使显示“通过”，实际上也没有测试任何内容。 在信任 Detox 结果之前，务必确认模拟器已启动且应用已安装。检查日志中是否出现 “No simulators found”。
• 音频/媒体功能在模拟器中无法正常工作。 麦克风、扬声器和某些媒体 API 在模拟器中的表现会有所不同，或者完全无法使用。请在实体设备上测试这些功能。
• 并行 swarm 需要隔离的模拟器。 两个 Agent 使用 booted 时会争用同一个模拟器。请为每个 Agent 创建带名称的模拟器（参见上文的“并行模拟器隔离”部分）。
• 本地构建与 EAS 构建使用不同的签名方式。 使用 xcrun simctl install 安装的本地构建使用模拟器签名。EAS 预览构建则使用你的配置文件进行 Ad Hoc 签名。不要混淆两者——它们对设备的要求不同。