用途
e2e-maestro 面向 React Native / Expo 应用，用于在仓库自有的 iOS 模拟器和 Android 模拟器上建立、编写并运行 Maestro 端到端流程，覆盖界面旅程、网络策略验证、大字号无障碍流程和截图基线比对。
主要能力
- 以固定版本安装 Maestro：install-maestro.sh 下载 2.10.0 并校验 SHA-256，解压到被 git 忽略的 tools/maestro/，运行时设置关闭分析、分析通知和更新检查的环境变量。
- 运行器只接受关闭广告的测试变体 Release 构建，拒绝 Debug 构建、生产变体和 buildExtra 不匹配的构建。
- 流程以契约文件中的 id: 选择元素，文本仅用于操作系统自有界面；状态通过每个 setup 一个 debug 链接设置，语言方向切换单独先行。
- 每个 Maestro 命令前指定设备与独占驱动端口，避免共享机器端口冲突。
- 运行期间在每台设备上用实时采样器验证网络策略：不在允许列表中的套接字会使运行失败，采样器未存活到结尾同样失败。
- 无障碍流程在最大字号下于手机和平板、按配置的语言（含从右到左语言）运行。
- 截图取自静止、确定性画面，固定状态栏时间、动画静止、固定日期；按平台维护基线，容忍度固定为 0.1 颜色距离下 0.2% 像素，不允许调高。
- 基线仅在有意识变更时更新：缩小到受影响集合、逐张打开 PNG 与差异、提交带 Gate-Change 尾注。
- 需要生产 SDK 行为或真实系统弹窗的流程放在声明的 manual 文件夹，运行器不列出。
- 提供 setup 检查、流程静态检查（可选 Maestro 自身 check-syntax）和运行报告检查脚本。
使用方式
先准备屏幕 testID 契约、调试链接契约、测试变体 Release 构建和 Java 17。安装模板后填写 productionAppIds、network、largeText、screenshots 及流程 testID，添加四个 npm 脚本并忽略 tools/maestro/。随后运行检查脚本、编写流程并做静态检查，再执行 npm run e2e:ios 与 npm run e2e:android，用报告检查脚本核对结果；UI 变更后运行截图矩阵并逐一打开变更 PNG 与差异。
适用场景
适用于需要在真实 Release 构建上验证端到端旅程、网络出站策略、大字号无障碍和跨平台截图一致性的 React Native / Expo 项目。
限制
资料只标注了 2026-10-14 在 Maestro 2.10.0、Expo SDK 57、React Native 0.86.3、Xcode 26.6 / iOS 26.5 运行时的验证；Android 事实在 API 35 观察，默认 API 36 镜像尚未端到端运行。采样器存活证明、分平台截图文件夹和双链接矩阵设置在验证运行之后加入，仅由自测和 Jest 证明。禁止使用 AI 命令及任何上传功能，禁止使用 Homebrew 或 curl | bash 安装，禁止在流程 env: 中设置 APP_ID、APP_SCHEME、LANG、THEME，禁止用重试或 sleep 掩盖不稳定流程。