argent-qa-e2e

创建 QA 回归端到端测试

加载 argent-create-e2e 作为编写引擎。遵循它要求的参考资料，了解录制器语法、选择器、润色、平台例外和修复。本技能补充 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；Runner 树是 describe 树（id 和 role 相同），因此在模拟器上编写的选择器可能无法在实体设备上命中。录制前阅读 argent-ios-device-interact，了解应用范围内的契约。

完成定义

只有满足以下条件，QA 端到端测试才算完成：

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

1. 定义测试契约

操作应用前，先编写一张简明表格。并在最终报告中重述。表格需包含：

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

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

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

让重复运行具有确定性：

1. 不做修改，检查所需基线。
2. 如果账户状态不干净，记录一个安全的重置或播种端到端测试。也可以在设置中加入安全的标准化操作。
3. 设置导航完成后，回显命名基线，并在首次场景变更前进行严格检查。使用 assert: 或能完整证明基线的目标 await:。
4. 尽量在结束时恢复基线。

端到端测试有两种夹具机制：

• run: 回放单独录制的重置或播种端到端测试。
• script: 执行所需的本地设置或清理操作。在操作演练中对应的位置使用 e2e-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-e2e 的启动顺序和实时编写流程。在每项结构性契约检查对应的状态出现时，将其记录下来。

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

3. 让证据具有区分性

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

绝不要将验收证据放在 when: 中。when: 仅用于最终会重新汇合到必需路径的可选设置。

4. 完成并审查

完成 create-e2e 的完善和阻塞项审查。然后：

1. 将每一行契约映射到已执行的操作或硬性检查。
2. 构建导航表，每次屏幕切换占一行，并列出身份门槛和就绪门槛。缺少任一项的行都属于阻塞缺陷。
3. 确认设置和结束状态允许立即进行第二次运行。

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

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

5. 证明连续通过两次

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

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

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

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

6. 报告

报告内容：

• E2E 测试名称、路径、平台和 CLI 命令。
• 将契约行映射到操作和检查项。
• 导航表。
• 基线设置、结束状态恢复和已接受的数据依赖项。
• 两项通过结果、运行器、新服务设置和已解决的警告。
• 快照范围、已审核的基线状态和不匹配容差。
• 坐标或原始手势例外。
• 剩余的人工判断或阻碍项。