argent-qa-flows

创建 QA 回归流程

加载 argent-create-flow 作为编写引擎。遵循其关于录制语法、选择器、润色、平台例外和修复的必需参考。本技能补充 QA 合约和完成门槛。

Vega 支持以下所有项目：launch: { vega: ... }、await:/assert: 选择器、snapshot: 和 idle 均可在其上运行。唯一缺少的是触控指令，因为 Vega 由远程驱动。使用录制的 tool: tv-remote 步骤导航，并使用 tool: keyboard 输入，因此第 5 项没有适用内容。D-pad 路径是相对于当前焦点位置而言的，因此每次移动都要通过第 4 项的身份检查设门，不要假定光标已落在目标位置。阅读 argent-tv-interact，了解焦点读取和遥控器导航。

Apple TV 和 Android TV 不在适用范围内。 Runner 不会在这两个平台上拒绝触控指令，因此错误会发生在手势层，而不是通过编写指导提示。请使用 argent-tv-interact 并报告此限制。

实体 iPhone 可运行 QA 流程，但有三个硬件限制：回放不会自动绑定手机，因此请将其 udid 作为 device 传入（CLI 使用 --device），并保持其处于 connected 状态；pinch/rotate 步骤会像实时工具一样在此失败，因此请改用应用自身的缩放 UI；流程树是 describe 树（id 和 role 相同），因此在模拟器上编写的选择器可能无法匹配实体设备。录制前请阅读 argent-ios-device-interact，了解应用范围内的合约。

完成定义

只有满足以下所有条件，QA 流程才算完成：

1. 第一个不是 echo: 或 script: 的步骤必须是 launch:。流程内的设置必须建立确定性数据基线。重复运行不会累积产物，也不需要手动清理。
2. 首次演练录制了每个操作和实时结构检查。只有三个有文档说明的润色插入项未录制。
3. 每项要求都对应一个硬性 await:、assert: 或经过审查的 snapshot:。Echo 和截图不构成判定。负向检查必须使用此前已确认可见的同一稳定选择器。
4. 每次屏幕变化后，都必须先确认目标屏幕身份，再通过 idle 确认就绪。
5. 目标必须符合稳定选择器和坐标回退规则。QA 仅对确实没有标签的目标保留坐标。在 Vega 上此项不适用，因为 Vega 没有坐标目标。
6. 未更改的 YAML 使用同一 runner 连续通过两次。第 1 次运行以全新的移动端 Argent 服务开始，第 2 次紧接其后运行。

1. 定义测试合约

操作应用之前，先编写一张简洁的表格。在最终报告中复述该表格。包括：

• 应用、平台和具名的起始状态。
• 按顺序排列的用户操作。
• 为每项预期结果、持久化规则或缺失声明各列一行。
• 每行对应的稳定、可执行证据。
• 所需数据和副作用。

语义状态使用结构检查，像素使用快照，混合要求则两者都用。一个行为场景对应一个 qa-<area>-<behavior> 流程。

不要臆造重要值，也不要弱化含糊之处。选择 UI 可验证的最强解释，并报告该解释。如果不同选择会改变测试含义，请先询问。

让重复运行保持确定性：

1. 不做修改，检查所需基线。
2. 如果账户状态不干净，录制安全的重置或播种流程。也可以在设置中加入安全的规范化操作。
3. 设置导航后，echo 具名基线，并在首次场景变更前进行硬性检查。使用 assert:，或使用能完整证明基线的目标 await:。
4. 尽量在结束时恢复基线。

流程有两种夹具机制：

• run: 回放单独录制的重置或播种流程。
• script: 执行请求的本地设置或清理操作。在演练中使用 flow-add-script 将其录制到对应位置。

在请求范围之外创建或删除有意义的用户数据前，请先询问。

紧凑示例

工单：在“设置”中选择“深色”。验证已选中“深色”、“浅色”不再显示，并且屏幕以深色模式呈现。

合约行	操作	证据	状态影响
已登录的主页	启动	await: { visible: { id: home-screen } }，然后 await: { idle: true }	现有账户
打开“设置”	点击 settings-tab	await: { visible: { id: settings-screen } }，然后 await: { idle: true }	无
证明已选中“浅色”	检查“设置”	assert: { visible: { id: theme-light-selected } }	如果已经是深色则失败
证明已选中“深色”	点击 theme-dark-option	await: { visible: { id: theme-dark-selected } }	主题变为深色
证明“浅色”不再显示	检查稳定后的屏幕	assert: { hidden: { id: theme-light-selected } }	无
验证深色呈现	检查稳定后的屏幕	snapshot: settings-dark	无
恢复基线	点击 theme-light-option	await: { visible: { id: theme-light-selected } }	下次运行从干净状态开始

初始的“浅色”检查建立了后续 hidden 检查使用的选择器。最后恢复状态可确保第 2 次运行相互独立。

2. 记录场景

遵循 argent-create-flow 的启动顺序和实时编写周期。在每项结构性合约检查对应的状态出现时记录它。

快照没有录制形式。演练期间检查其稳定状态，然后在润色阶段添加计划中的快照。如果直接恢复会改变状态，请重新记录受影响的行为。恢复后的演练不能作为证明。

3. 让证据具有区分性

• **状态变更：**证明新状态成立，并在旧状态仍可能匹配时证明旧状态已不存在。
• **取消／持久化：**跨越提交边界。取消或保存后，离开并重新进入，然后验证存储状态：取消后保持不变，保存后已更新。
• **不存在：**证明所在屏幕存在，并将同一个稳定选择器记录为 visible，然后执行操作，再检查 hidden。不要仅为强化正向基线而添加未经验证的 hidden 检查。在集合中，视口内不存在不代表全局不存在。使用固定的种子位置、计数、空状态或其他覆盖整个集合的证据。
• **覆盖层：**使用创建流程中的被遮挡目标处理流程。
• **重复控件：**优先使用 id。否则，仅在流程中使用带稳定容器的 within。使用 text.in 证明容器内呈现了相应内容。
• **动态内容：**断言受控状态或稳定的应用界面元素。对于无法避免的动态值，使用锚定结构并说明其依赖项。
• **视觉状态：**仅对正确、稳定且确定的屏幕进行快照。全局变更使用全屏快照，单个组件使用 cropOn。

切勿将验收证据放入 when:。when: 仅用于可选设置，且必须能重新汇合到必需路径。

4. 完成并审计

完成创建流程的润色和阻塞项审计。然后：

1. 将每一行契约映射到已执行的操作或硬性检查。
2. 构建导航表，每次屏幕切换占一行，并注明身份门槛和就绪门槛。缺少其中任一项的行都是阻塞缺陷。
3. 确认设置和最终状态允许立即再次运行。

操作	目标	身份	就绪状态
点击 settings-tab	设置	settings-screen 可见	idle

这两项的修复方式不同。缺少身份检查时，必须在恢复后的屏幕上实时记录。缺少 idle 检查时，则在 YAML 中添加，因为 await: { idle: true } 没有录制形式，而且是 argent-create-flow 允许的三项润色插入之一。重新录制缺少的任何操作或其他结构检查。

5. 证明连续通过两次

完成最后一次编辑和审查后，将连续通过次数重置为零：

1. 两次验证都使用同一个运行器。在本地使用 flow-execute，或在 CI 中使用 argent flow run <name> --platform <platform>。切换运行器会重置连续通过次数。
2. 创建、审查并冻结快照基线。更新基线不计为通过。
3. 第一次移动端验证前，重启此流程所用设备的 Argent 服务：两次热启动通过属于相关证据，因为如果环境速度没有变化，固定的时间余量可能让测试连续通过两次。将 stop-all-simulator-servers 的范围限定为 devices: [<device>]。绝不要省略范围：不带范围的调用会扫描整台机器，而第 7 步会频繁重启此验证，导致反复清理所有其他 Agent 的设备。使用 flow-execute 的 MCP 调用，或从独立运行器的安装目录运行 argent run stop-all-simulator-servers --devices <device>。重置不得更改应用或账号数据。对于 Chromium，让运行器启动已声明的应用，并省略 device。Vega 不使用可重启的 Argent 服务，因此无需执行清理，且两次验证都属于热启动。
4. 从流程的启动和设置步骤开始运行，不启用基线更新模式。只有在 ok: true 且所有验收检查都已执行时，才计为通过。when: 为 false 时，只能跳过可选设置。发生错误的步骤不会增加连续通过次数；错误分为两类，请逐条查看原因。无法运行的步骤（例如 idle 下无法读取树，或无法解析的 run: 目标）属于环境问题：修复后重新运行。launch: 失败也会被判定为 errored，这是对应用的判定；应用无法安装或启动正是此测试要发现的回归，因此应报告，而不是重新运行。
5. 完成前，解决所有通过步骤的警告。也要解决 flow-finish-recording 记录的等待警告。请参阅实时等待和检查。对于运行器警告，await: { idle: true } 会产生六种不同的警告，因此要先确认具体是哪一种。其中两种表示屏幕仍在移动。一种表示等待期间超时，需要增大 timeout:。一种表示树一直为空。一种表示仅根据 UI 树判断已稳定，也就是说层级结构确实保持静止，只是缺少成对的屏幕截图，因此应检查捕获路径，而不是应用的渲染。还有一种表示步骤结束时没有任何证据。检查屏幕，说明原因，并确认周边的验收检查依赖的是稳定元素，而不是静止状态。不带选择器的手势（坐标 tap／long-press／swipe，或没有 on: 的 pinch／rotate）会以另一种形式显示警告：树数据源不可用，导致手势未能确认目标，因此系统盲目发送了手势；绿色结果只能说明手势已发送。恢复树数据源，通常重新启动应用以加载检测代码，然后重新运行。只有不提供树数据的应用才可能接受此警告，而这类应用无论如何都无法满足此契约。
6. 立即使用同一个运行器再次运行相同的 YAML。不要手动重置应用或账号数据。
7. 发生任何失败、编辑、重新录制、基线更新或会改变状态的手动恢复后，都要重置连续通过次数。通过 argent-create-flow 修复，再次审查，并在重新启动服务后重新开始验证。

连续通过次数达到两次后才能完成。如果无法使用预期的运行器，请报告验证受阻。如果产品行为未通过，请保留强有力的检查并报告回归。绝不要为了获得绿色结果而削弱检查。

记录所用的运行器和新服务设置。

6. 报告

报告内容：

• 流程名称、路径、平台和独立命令。
• 合约行与操作和检查的对应关系。
• 导航表。
• 基线设置、结束状态恢复和已接受的数据依赖。
• 两项通过结果、运行器、全新服务设置和已解决的警告。
• 快照范围、已审核的基线状态和不匹配容忍度。
• 坐标或原始手势例外。
• 剩余的人工判断或阻碍。