argent-create-e2e

创建 Argent 端到端测试

Argent 端到端测试是 .argent/e2e/<name>.yaml 中一段可重放的步骤序列（仍会读取 .argent/flows/）。

对于已保存的 QA 测试用例、工单或验收标准，请先加载 argent-qa-e2e。它会添加确定性的设置、验收证据和两轮验证。

阅读相关参考资料

• 创建或修改端到端测试之前，请完整阅读 实时编写。
• 润色、编写或手动审查 YAML 时，请阅读 端到端 YAML。对于 Vega，在录制远程或键盘工具之前，请阅读其平台限制。
• 端到端测试运行于实体 iPhone（iOS list-devices 中 kind 为 "device" 的条目），但重放时绝不会自动绑定设备，即使没有模拟器启动也是如此：请将手机的 udid 作为 device 传入（CLI 使用 --device），且只有处于 connected 状态的手机才能运行。pinch/rotate 步骤在实体设备上会像实时工具一样失败。在硬件上，运行器树是 describe 树：具有相同的 id 和 role，没有 UIView 层级结构。硬件契约请参阅 argent-ios-device-interact。
• 出现捕获警告、原始坐标、树不可用、转换时机错误、覆盖层或重放失败时，请阅读 可靠性与恢复。

不可妥协的规则

1. 录制首次操作流程。 在首次启动或应用内操作之前启动录制器。不要重构排练过的路径。
2. 在状态出现时录制检查。 实时录制 await-ui-element，然后在润色时转换它。echo 记录的是意图或诊断上下文，而非应用行为或判定。截图是供人查看的证据，不是可执行的判定。对于元素不存在的情况，先将同一选择器录制为 visible，执行移除操作，然后再将其录制为 hidden。
3. 使用语义化目标。 优先使用严格 id，其次使用稳定文本或无障碍标签。对于屏幕外元素，使用 scroll-to。按照 坐标回退门槛 立即处理所有原始点警告。
4. 验证每次屏幕变化。 录制仅用于识别目标页面的检查。润色时，在其后添加 await: { idle: true }。静止不能证明页面身份，且 idle 可能在出现警告的情况下通过。
5. 仅润色已执行的行为。 转换已录制的步骤，不要改变其含义。任何缺失的操作或结构检查都必须实时录制。唯一允许插入而不录制的内容是计划中的 snapshot:、导航用的 await: { idle: true }，以及有文档说明的 Chromium 打包 launch:。
6. 仅在用户要求时使用脚本。 阅读 端到端 YAML：本地脚本，然后使用 e2e-add-script 录制每个脚本。
7. 从头到尾重放最终 YAML。 常规端到端测试需要一次不中断的完整通过。argent-qa-e2e 要求连续通过两次。

稳定选择器

稳定选择器由应用代码固定，并且在端到端测试支持的所有账户、数据、时间、数量、顺序、语言区域和环境下都保持不变。优先使用 settings-screen 这类 id。不要使用 Today、Item 4、用户名、计数器或时间戳等值作为门槛。

仅限 YAML 的选择器范围

润色时，使用 within、after 和 next 来区分重复元素。请阅读 端到端 YAML：关系范围，了解其基于框架的语义和失败情况。

工作流

1. 选择端到端测试类型：
   • 独立测试： 第一个不是 echo: 或 script: 的步骤是 launch:。测试负责控制进程启动。
   • 片段： 开头没有 launch。请声明精确的 executionPrerequisite。
2. 按照 实时编写 执行：启动、一次录制并验证一个步骤、完成、润色、审查并重放。
3. 报告文件、重放命令、结果、前置条件或副作用，以及每项坐标或原始手势例外。

主动录制

重复三次或更多次交互之前，告知用户并开始录制。录制本次运行，并在之后回放。已完成的流程无法追溯录制。

修复

回放失败时，按照 可靠性与恢复 处理。检查首次偏差，修正有充分依据的最小单元，进行审计，并回放完整的端到端测试。两轮修正均未成功后即停止。绝不要为了通过检查而降低用户要求的检查标准。