argent-create-flow

创建 Argent flow

Argent flow 是 .argent/flows/<name>.yaml 中可重放的操作序列。

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

阅读相关参考资料

• 创建或更改 flow 前，请完整阅读 实时编写。
• 润色、组合或手动审查 YAML 时，请阅读 Flow YAML。对于 Vega，在录制远程工具或键盘工具前，请阅读其平台限制。
• Flow 在实体 iPhone 上运行（list-devices 中 kind 为 "device" 的条目），但重放时绝不会自动绑定设备，即使没有模拟器启动也一样：请将手机的 udid 作为 device 传入（CLI 使用 --device），且只有已连接（connected）的手机才能运行。pinch/rotate 步骤在实体设备上会像实时工具一样失败。在硬件上，flow 树就是 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. 仅在用户要求时使用脚本。 阅读 Flow YAML：本地脚本，然后使用 flow-add-script 录制每个脚本。
7. 端到端重放最终 YAML。 普通 flow 需要一次不中断的完整运行。argent-qa-flows 要求连续运行两次。

稳定选择器

稳定选择器由应用代码固定，在 flow 支持的所有账户、数据、时间、数量、顺序、地区设置和环境中都保持不变。优先使用 settings-screen 等 id。不要使用 Today、Item 4、用户名、计数器或时间戳等值作为门控条件。

仅用于 Flow 的选择器范围

润色时，使用 within、after 和 next 来消除重复元素的歧义。有关其基于框架的语义和失败情形，请阅读 Flow YAML：关系范围。

工作流

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

主动录制

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

修复

回放失败时，请遵循 可靠性与恢复。检查首次偏差，修正有充分理由的最小单元，进行审核，并回放完整流程。两轮修正均未成功后停止。绝不要为了通过检查而降低用户要求的检查标准。