argent-qa-flows

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create a QA regression flow

创建QA回归流程

Load

argent-create-flow

as the authoring engine. Follow its required references for recorder syntax, selectors, polish, platform exceptions, and repair. This skill adds the QA contract and completion gate.

Vega supports every item below:

launch: { vega: ... }

await:

assert:

selectors,

snapshot:

, and

idle

all run there. Only the touch directives are missing, because Vega is remote-driven. Navigate with recorded

tool: tv-remote

steps and type with

tool: keyboard

, which leaves item 5 with nothing to govern. A D-pad path is relative to where focus already is, so gate every move with item 4's identity check rather than assuming the cursor landed. Read

argent-tv-interact

for focus reading and remote navigation.

Apple TV and Android TV are out of scope. The runner does not reject touch directives there, so they fail at the gesture layer instead of with authoring guidance. Use

argent-tv-interact

and report the limitation.

加载

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不在支持范围内。运行器不会在这些平台拒绝触摸指令，因此它们会在手势层失败，而非给出创作指导。请使用

argent-tv-interact

并报告该限制。

Definition of done

完成定义

A QA flow is complete only when:

The first non-echo step is
```
launch:
```
. In-flow setup proves a deterministic data baseline. Repeated runs do not accumulate artifacts or require manual cleanup.
The first walkthrough recorded every action and live structural check. Only the three documented polish insertions are unrecorded.
Every requirement maps to a hard
```
await:
```
,
```
assert:
```
, or reviewed
```
snapshot:
```
. Echoes and screenshots are not verdicts. A negative check needs the same stable selector established as visible earlier.
Every screen change has destination identity followed by
```
idle
```
readiness.
Targets satisfy the stable-selector and coordinate-fallback rules. QA keeps coordinates only for genuinely unlabeled targets. Vacuous on Vega, which has no coordinate targets.
The unchanged YAML passes twice with the same runner. Pass 1 starts with fresh mobile Argent services, and pass 2 follows immediately.

QA流程需满足以下条件才算完成：

第一个非回显步骤为
```
launch:
```
。流程内设置需确保确定性数据基线。重复运行不会累积 artifacts 或需要手动清理。
首次演练需记录所有操作和实时结构校验。仅允许插入三类文档中规定的优化内容，其余内容均需录制。
每项需求都对应一个硬性的
```
await:
```
、
```
assert:
```
或已审核的
```
snapshot:
```
。回显和截图不算作判定结果。否定校验需使用之前已确认可见的相同稳定选择器。
每次屏幕切换都需先校验目标身份，再进行
```
idle
```
就绪校验。
目标需符合稳定选择器和坐标回退规则。QA仅对真正无标签的目标保留坐标。此规则对Vega不适用，因为Vega没有坐标目标。
未修改的YAML需在同一运行器上连续两次通过。第一次运行需启动全新的移动端Argent服务，第二次运行需紧随第一次之后。

1. Define the test contract

1. 定义测试契约

Before touching the app, write a compact table. Restate it in the final report. Include:

App, platform, and named start state.
Ordered user actions.
One row for each expected outcome, persistence rule, or absence claim.
Stable executable evidence for each row.
Required data and side effects.

Use structural checks for semantic state, snapshots for pixels, and both for mixed requirements. One behavioral scenario becomes one

qa-<area>-<behavior>

flow.

Do not invent a material value or weaken ambiguity. Choose the strongest UI-verifiable reading and report it. Ask when the choice changes test meaning.

Make repeated runs deterministic:

Inspect the required baseline without mutation.
If the account is dirty, record a safe reset or seed flow. Alternatively, include safe normalization in setup.
After setup navigation, echo the named baseline and hard-check it before the first scenario mutation. Use
```
assert:
```
or a destination
```
await:
```
that fully proves the baseline.
Prefer to restore the baseline at the end.

Use

run:

for a separately recorded reset or seed flow. No other fixture mechanism exists. Ask before cleanup that creates or deletes meaningful user data outside the request.

在操作应用之前，编写一个简洁的表格，并在最终报告中重述。表格需包含：

应用、平台及指定起始状态。
有序的用户操作。
每行对应一个预期结果、持久化规则或不存在性声明。
每行对应的稳定可执行证据。
所需数据及副作用。

语义状态使用结构校验，像素状态使用快照，混合需求则两者结合。一个行为场景对应一个

qa-<area>-<behavior>

流程。

请勿自行设定具体值或弱化歧义。选择最适合UI验证的解读方式并报告。若选择会改变测试含义，请先询问。

确保重复运行的确定性：

检查所需基线且不修改其状态。
若账户状态异常，录制安全重置或初始化流程。或者在设置中加入安全标准化步骤。
设置导航完成后，回显指定基线并在首次场景修改前进行硬性校验。使用
```
assert:
```
或目标
```
await:
```
来充分验证基线。
优先在流程结束时恢复基线状态。

使用

run:

调用单独录制的重置或初始化流程。不存在其他固定机制。若清理操作会在请求外创建或删除有意义的用户数据，请先询问。

Compact example

简洁示例

Ticket: select Dark in Settings. Verify Dark is selected, Light is absent, and the screen renders in dark mode.

Contract row	Action	Evidence	State effect
Signed-in Home	Launch	`await: { visible: { id: home-screen } }` , then `await: { idle: true }`	Existing account
Open Settings	Tap `settings-tab`	`await: { visible: { id: settings-screen } }` , then `await: { idle: true }`	None
Prove Light selected	Inspect Settings	`assert: { visible: { id: theme-light-selected } }`	Fails if already Dark
Prove Dark selected	Tap `theme-dark-option`	`await: { visible: { id: theme-dark-selected } }`	Theme becomes Dark
Prove Light absent	Inspect settled screen	`assert: { hidden: { id: theme-light-selected } }`	None
Verify dark rendering	Inspect settled screen	`snapshot: settings-dark`	None
Restore baseline	Tap `theme-light-option`	`await: { visible: { id: theme-light-selected } }`	Next run starts clean

The initial Light check establishes the selector used by the later

hidden

check. The final restore makes pass 2 independent.

工单：在设置中选择深色模式。验证深色模式已选中、浅色模式未选中，且屏幕以深色模式渲染。

契约行	操作	证据	状态影响
已登录首页	启动应用	`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. Record the scenario

2. 录制场景

argent-create-flow

's start order and live-authoring cycle. Record each structural contract check when its state appears.

A snapshot has no recorder form. Inspect its stable state during the walkthrough, then add the planned snapshot during polish. If direct recovery changes state, re-record the affected behavior. A recovered walkthrough is not proof.

遵循

argent-create-flow

的启动顺序和实时创作周期。当对应状态出现时，记录每个结构契约校验。

快照没有录制器形式。演练期间检查其稳定状态，然后在优化阶段添加计划好的快照。若直接恢复操作改变了状态，请重新录制受影响的行为。恢复后的演练不算作有效证据。

3. Make evidence discriminating

3. 提升证据的区分度

State change: prove the new state and the old state's absence when both can otherwise match.
Cancel/persistence: cross the commit boundary. After cancel or save, leave, re-enter, then verify the stored state: unchanged after cancel or updated after save.
Absence: prove the containing screen and record the same stable selector as
```
visible
```
, then the action, then
```
hidden
```
. Do not add an unestablished
```
hidden
```
check only to strengthen a positive baseline. In a collection, viewport absence is not global absence. Use fixed seeded position, count, empty state, or other collection-wide evidence.
Overlays: use the create-flow obscured-target procedure.
Repeated controls: prefer an id. Otherwise use flow-only
```
within
```
with a stable container. Use
```
text.in
```
to prove rendered membership inside that container.
Dynamic content: assert controlled state or stable app chrome. Use anchored structure for unavoidable dynamic values and disclose the dependency.
Visual state: snapshot only a correct, settled, deterministic screen. Use full screen for global changes and
```
cropOn
```
for one component.

Never put acceptance evidence inside

when:

. Use

when:

only for optional setup that reconverges to the required path.

状态变更：当新旧状态可能混淆时，需证明新状态存在且旧状态已消失。
取消/持久化：跨越提交边界。取消或保存后，离开并重新进入页面，然后验证存储状态：取消后状态不变，保存后状态更新。
不存在性：先证明容器屏幕存在，并记录相同的稳定选择器为
```
visible
```
，执行操作后再记录为
```
hidden
```
。请勿仅为强化阳性基线而添加未确立的
```
hidden
```
校验。在集合中，视口中不存在不代表全局不存在。使用固定的初始化位置、计数、空状态或其他集合级证据。
覆盖层：使用create-flow的遮挡目标处理流程。
重复控件：优先使用id。否则使用流程专属的
```
within
```
搭配稳定容器。使用
```
text.in
```
证明该容器内存在渲染内容。
动态内容：校验受控状态或稳定的应用框架。对不可避免的动态值使用锚定结构，并披露依赖关系。
视觉状态：仅对正确、稳定、确定性的屏幕进行快照。全局变更使用全屏快照，单个组件使用
```
cropOn
```
。

请勿将验收证据放入

when:

中。

when:

仅用于可选设置，且需收敛到所需路径。

4. Finish and audit

4. 完成并审核

Complete the create-flow polish and blocking audit. Then:

Map every contract row to an executed action or hard check.
Build a navigation table with one row per screen change, naming both the identity gate and the readiness gate. A row missing either is a blocking defect.
Confirm setup and end state permit an immediate second run.

Action	Destination	Identity	Readiness
Tap `settings-tab`	Settings	`settings-screen` visible	`idle`

The two are repaired differently. A missing identity check must be recorded live on the restored screen. A missing

idle

check is added in YAML, because

await: { idle: true }

has no recorder form and is one of

argent-create-flow

's three permitted polish insertions. Re-record any missing action or other structural check.

完成create-flow的优化和阻塞性审核后：

将每个契约行映射到已执行的操作或硬性校验。
构建导航表，每行对应一次屏幕切换，同时标明身份校验和就绪校验。缺少任一校验的行均为阻塞性缺陷。
确认设置和结束状态允许立即进行第二次运行。

操作	目标页面	身份校验	就绪校验
点击 `settings-tab`	设置页面	`settings-screen` 可见	`idle`

两种校验的修复方式不同。缺失的身份校验必须在恢复后的屏幕上实时录制。缺失的

idle

校验需在YAML中添加，因为

await: { idle: true }

没有录制器形式，且是

argent-create-flow

允许的三类优化插入内容之一。重新录制任何缺失的操作或其他结构校验。

5. Prove two consecutive passes

5. 验证连续两次通过

After the last edit and audit, set the streak to zero:

Choose one runner for both passes. Use
```
flow-execute
```
locally or
```
argent flow run <name> --platform <platform>
```
for CI. Switching runners resets the streak.
Seed, review, and freeze snapshot baselines. Baseline updates do not count as passes.
Before mobile pass 1, recycle Argent services for this flow's device: two warm passes are correlated evidence, because a fixed timing margin can pass twice simply because environment speed did not change. Scope
```
stop-all-simulator-servers
```
to
```
devices: [<device>]
```
. Never omit the scope — a bare call is the machine-wide sweep, and step 7 restarts this proof often enough to reap every other agent's devices repeatedly. Use the MCP call for
```
flow-execute
```
, or
```
argent run stop-all-simulator-servers --devices <device>
```
from the standalone runner's install. The reset must not change app or account data. For Chromium, let the runner boot the declared app and omit
```
device
```
. Vega owns no recyclable Argent services, so the teardown is a no-op there and both passes are warm.
Run from the flow's launch and setup without baseline-update mode. Count a pass only when
```
ok: true
```
and every acceptance check executed. A false
```
when:
```
can skip optional setup only. An errored step does not advance the streak, and the count mixes two kinds — read each reason. One that could not run (an unreadable tree under
```
idle
```
, an unresolvable
```
run:
```
target) is environment: fix it and rerun. A failed
launch:
also scores
errored
, and it is a verdict about the app — an app that no longer installs or starts is the regression this test exists to catch, so report it instead of rerunning.
Resolve every passing-step warning before completion.
```
await: { idle: true }
```
raises six different warnings, so read which one it is first. Two say the screen was moving. One says the wait ran out mid-hold and needs a larger
```
timeout:
```
. One says the tree stayed empty. One — settled on the UI tree alone — says the hierarchy did hold still and only the screenshot pairs were missing, so inspect the capture path rather than the app's rendering. One says the step ended with no evidence either way. Inspect the screen, disclose the cause, and verify that surrounding acceptance checks use stable elements rather than stillness.
Run the same YAML again immediately with the same runner. Do not manually reset app or account data.
Reset the streak after any failure, edit, re-recording, baseline update, or state-changing manual recovery. Repair through
```
argent-create-flow
```
, audit again, and restart with fresh services.

Finish only when the streak reaches two. If the intended runner is unavailable, report proof as blocked. If product behavior fails, keep the strong check and report the regression. Never weaken it to obtain green output.

Record the runner and fresh-service setup used.

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

为两次运行选择同一个运行器。本地使用
```
flow-execute
```
，CI环境使用
```
argent flow run <name> --platform <platform>
```
。切换运行器会重置连续通过次数。
初始化、审核并冻结快照基线。基线更新不算作通过。
移动端第一次运行前，为此流程的设备重启Argent服务：两次热启动运行的证据具有相关性，因为固定的时间裕度可能仅因环境速度未变而连续通过两次。将
```
stop-all-simulator-servers
```
的范围限定为
```
devices: [<device>]
```
。切勿省略范围——无范围的调用会扫描整个机器，且第7步会频繁重启验证流程，可能会影响其他代理的设备。
```
flow-execute
```
使用MCP调用，独立运行器则使用
```
argent run stop-all-simulator-servers --devices <device>
```
。重置操作不得修改应用或账户数据。对于Chromium，让运行器启动指定的应用，无需指定
```
device
```
。Vega没有可重启的Argent服务，因此无需清理，两次运行均为热启动。
从流程的启动和设置阶段开始运行，不启用基线更新模式。仅当
```
ok: true
```
且所有验收校验均已执行时，才算一次通过。
```
when:
```
为false时仅可跳过可选设置。出错的步骤不会增加连续通过次数，需查看每个错误原因。无法运行的情况（
```
idle
```
下不可读的树、无法解析的
```
run:
```
目标）属于环境问题：修复后重新运行。launch:
失败也会标记为
errored
，这是关于应用的判定结果——无法安装或启动的应用正是此测试旨在发现的回归问题，因此需报告而非重新运行。
完成前解决所有通过步骤的警告。
```
await: { idle: true }
```
会触发六种不同的警告，请先查看具体警告类型。其中两种表示屏幕在移动，一种表示等待超时需增大
```
timeout:
```
值，一种表示树始终为空，一种——仅UI树稳定——表示层级已稳定但缺少截图对比，请检查捕获路径而非应用渲染，还有一种表示步骤未产生任何证据。检查屏幕、披露原因，并验证周边验收校验使用的是稳定元素而非静止状态。
立即使用同一运行器再次运行相同的YAML。请勿手动重置应用或账户数据。
任何失败、编辑、重新录制、基线更新或改变状态的手动恢复操作后，均需重置连续通过次数。通过
```
argent-create-flow
```
修复问题，再次审核，并使用全新服务重启验证。

仅当连续通过次数达到两次时才算完成。若指定运行器不可用，需报告验证被阻塞。若产品行为失败，请保留强校验并报告回归问题。切勿为了获得绿色输出而弱化校验。

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

6. Report

6. 报告

Report:

Flow name, path, platform, and standalone command.
Contract rows mapped to actions and checks.
Navigation table.
Baseline setup, end-state restoration, and accepted data dependencies.
Both pass results, runner, fresh-service setup, and resolved warnings.
Snapshot scope, reviewed baseline status, and mismatch tolerance.
Coordinate or raw-gesture exceptions.
Remaining manual judgment or blocker.

报告需包含：

流程名称、路径、平台及独立运行命令。
映射到操作和校验的契约行。
导航表。
基线设置、结束状态恢复及已接受的数据依赖。
两次通过的结果、运行器、全新服务设置及已解决的警告。
快照范围、已审核的基线状态及不匹配容差。
坐标或原始手势异常。
剩余的人工判断或阻塞问题。