argent-qa-e2e

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create a QA regression e2e test

创建 QA 回归 e2e 测试

Load

argent-create-e2e

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.

Physical iPhones run QA e2e tests, with three hardware limits: replay never auto-binds a phone, so pass its udid as

device

(CLI

--device

) and keep it

connected

;

pinch

rotate

steps fail there like the live tools, so drive the app's own zoom UI instead; the runner tree is the

describe

tree (same ids and roles), so a selector authored on a simulator can miss there. Read

argent-ios-device-interact

for the app-scoped contract before recording.

将

argent-create-e2e

作为创作引擎加载。遵循其关于 recorder 语法、选择器、polish、平台例外和修复流程的必需参考文档。本 skill 在此基础上增加 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 e2e 测试，但存在三项硬件限制：回放永远不会自动绑定手机，因此需要将其 udid 作为

device

（CLI

--device

）传入，并保持设备处于

connected

状态；

pinch

rotate

步骤会像实时工具一样在该设备上失败，因此应改为操作应用自身的缩放 UI；runner tree 就是

describe

tree（具有相同的 id 和 role），因此在模拟器上创作的选择器可能无法在该设备上匹配。录制前请阅读

argent-ios-device-interact

，了解应用范围内的契约。

Definition of done

完成定义

A QA e2e test is complete only when:

The first step that is not
```
echo:
```
or
```
script:
```
is
```
launch:
```
. In-test 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 e2e 测试才算完成：

第一个不是
```
echo:
```
或
```
script:
```
的步骤必须是
```
launch:
```
。测试内 setup 应证明数据基线具有确定性。重复运行不会累积测试产物，也不需要手动清理。
首次 walkthrough 录入了每个操作和实时结构检查。只有文档明确允许的三处 polish 插入无需录入。
每项需求都映射到一个硬性
```
await:
```
、
```
assert:
```
或已审阅的
```
snapshot:
```
。Echo 和截图不能作为判定结果。否定检查需要使用此前已确认可见的同一稳定选择器。
每次界面变化后，都必须先确认目标标识，再检查
```
idle
```
就绪状态。
目标必须满足稳定选择器和坐标回退规则。QA 仅对确实没有标签的目标保留坐标。Vega 没有坐标目标，因此该规则不适用。
未修改的 YAML 使用同一个 runner 连续通过两次。第 1 次运行使用全新的移动端 Argent 服务，第 2 次运行紧随其后执行。

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>

e2e test.

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 e2e test. 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.

An e2e test has two fixture mechanisms:

```
run:
```
replays a separately recorded reset or seed e2e test.
```
script:
```
runs requested local setup or cleanup. Record it with
```
e2e-add-script
```
where it belongs in the walkthrough.

Ask before cleanup that creates or deletes meaningful user data outside the request.

在操作应用之前，先编写一个紧凑的表格，并在最终报告中重新陈述该表格。表格应包括：

应用、平台和命名的初始状态。
有序的用户操作。
每一项预期结果、持久性规则或不存在性声明各占一行。
每一行对应的稳定可执行证据。
所需数据和副作用。

对于语义状态，使用结构检查；对于像素，使用 snapshot；对于混合需求，两者同时使用。一个行为场景对应一个

qa-<area>-<behavior>

e2e 测试。

不要虚构实质值，也不要削弱原有歧义。选择可通过 UI 验证的最强解释，并在报告中说明。如果某种选择会改变测试含义，应先询问。

通过以下方式让重复运行具有确定性：

在不修改状态的情况下检查所需基线。
如果账户数据处于脏状态，请录制一个安全的重置或 seed e2e 测试 Alternatively，可在 setup 中包含安全归一化操作。
完成 setup 导航后，echo 命名基线，并在第一次场景变更前对其进行硬性检查。使用
```
assert:
```
或目标
```
await:
```
完整证明基线成立。
优先在测试结束时恢复基线。

e2e 测试有两种 fixture 机制：

```
run:
```
回放单独录制的 reset 或 seed e2e 测试。
```
script:
```
运行请求的本地 setup 或 cleanup。使用
```
e2e-add-script
```
在 walkthrough 中对应位置录制它。

如果清理操作会在请求范围之外创建或删除重要的用户数据，应先询问。

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.

任务单：在 Settings 中选择 Dark。验证 Dark 已选中、Light 不存在，并且界面以深色模式渲染。

契约行	操作	证据	状态影响
已登录的 Home	Launch	`await: { visible: { id: home-screen } }` ，然后 `await: { idle: true }`	现有账户
打开 Settings	Tap `settings-tab`	`await: { visible: { id: settings-screen } }` ，然后 `await: { idle: true }`	无
证明 Light 已选中	检查 Settings	`assert: { visible: { id: theme-light-selected } }`	如果已是 Dark，则失败
证明 Dark 已选中	Tap `theme-dark-option`	`await: { visible: { id: theme-dark-selected } }`	主题变为 Dark
证明 Light 不存在	检查稳定后的界面	`assert: { hidden: { id: theme-light-selected } }`	无
验证深色渲染	检查稳定后的界面	`snapshot: settings-dark`	无
恢复基线	Tap `theme-light-option`	`await: { visible: { id: theme-light-selected } }`	下次运行从干净状态开始

初始的 Light 检查建立了后续

hidden

检查所使用的选择器。最终的恢复操作使第 2 次运行不依赖前一次运行。

2. Record the scenario

2. 录制场景

argent-create-e2e

'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-e2e

的启动顺序和实时创作周期。每当相应状态出现时，录入每一项结构契约检查。

snapshot 没有 recorder 形式。在 walkthrough 期间检查其稳定状态，然后在 polish 阶段添加计划中的 snapshot。如果直接恢复操作改变了状态，应重新录制受影响的行为。恢复后的 walkthrough 不构成证据。

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-e2e obscured-target procedure.
Repeated controls: prefer an id. Otherwise use YAML-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
```
检查。在集合中，viewport 内不存在并不代表全局不存在。应使用固定且已 seed 的位置、数量、空状态或其他集合级证据。
**浮层：**使用 create-e2e 的遮挡目标流程。
**重复控件：**优先使用 id。否则使用仅可在 YAML 中使用的
```
within
```
，并指定稳定的容器。使用
```
text.in
```
证明内容确实呈现在该容器内。
**动态内容：**断言受控状态或稳定的应用框架。对于无法避免的动态值，使用锚定结构，并披露相关依赖。
**视觉状态：**仅对正确、稳定且具有确定性的界面使用 snapshot。对于全局变化使用全屏，对于单个组件使用
```
cropOn
```
。

永远不要将验收证据放入

when:

中。

when:

仅用于能够重新汇入所需路径的可选 setup。

4. Finish and audit

4. 完成并审计

Complete the create-e2e 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-e2e

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

完成 create-e2e 的 polish 和阻断性审计。然后：

将每一个契约行映射到已执行的操作或硬性检查。
构建导航表，每次界面变化占一行，同时列出目标标识门禁和就绪门禁。缺少其中任意一项都是阻断性缺陷。
确认 setup 和结束状态允许立即执行第 2 次运行。

操作	目标界面	标识	就绪
Tap `settings-tab`	Settings	`settings-screen` 可见	`idle`

这两类缺失的修复方式不同。缺少标识检查时，必须在恢复后的界面上实时录制。缺少

idle

检查时，应在 YAML 中添加，因为

await: { idle: true }

没有 recorder 形式，并且它是

argent-create-e2e

允许的三处 polish 插入之一。如果缺少操作或其他结构检查，应重新录制。

5. Prove two consecutive passes

5. 证明连续两次通过

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

Choose one runner for both passes. Use
```
e2e-execute
```
locally or
```
argent e2e 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 test'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
```
e2e-execute
```
, or
```
argent run stop-all-simulator-servers --devices <device>
```
from the CLI'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 test'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. Also resolve recorded-wait warnings from
```
e2e-finish-recording
```
. Follow Live waits and checks. For runner warnings,
```
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. A selector-less gesture (a coordinate
```
tap
```
/
```
long-press
```
/
```
swipe
```
, or a
```
pinch
```
/
```
rotate
```
with no
```
on:
```
) warns in a different shape: a tree-source outage left it unsettled, so it dispatched blind and the green says only that the gesture was sent. Restore the tree source, usually by relaunching the app so the instrumentation loads, and rerun. Accepting that warning needs an app that serves no tree, which cannot satisfy this contract anyway.
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-e2e
```
, 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.

完成最后一次编辑和审计后，将连续通过计数归零：

两次运行选择同一个 runner。可以在本地使用
```
e2e-execute
```
，或在 CI 中使用
```
argent e2e run <name> --platform <platform>
```
。切换 runner 会重置连续通过计数。
Seed、审阅并冻结 snapshot 基线。更新基线不计入通过次数。
在移动端第 1 次运行前，为测试所用设备回收 Argent 服务：两次热运行属于相关性证据，因为固定的时间余量可能仅仅由于环境速度没有变化而连续通过两次。将
```
stop-all-simulator-servers
```
限定为
```
devices: [<device>]
```
。绝不能省略范围：不带范围的调用会清扫整台机器，而第 7 步会频繁重新开始这项验证，足以反复停止其他 agent 的设备。对于
```
e2e-execute
```
，使用 MCP 调用；或者从 CLI 安装位置执行
```
argent run stop-all-simulator-servers --devices <device>
```
。重置不得改变应用或账户数据。对于 Chromium，让 runner 启动声明的应用，并省略
```
device
```
。Vega 没有可回收的 Argent 服务，因此 teardown 在该平台上不执行任何操作，两次运行均为热运行。
从测试的 launch 和 setup 开始运行，不使用基线更新模式。只有在
```
ok: true
```
且每项验收检查都已执行时，才计为一次通过。值为 false 的
```
when:
```
只能跳过可选 setup。报错的步骤不会推进连续通过计数，而且计数中会混合两类情况，需要阅读具体原因。如果某个步骤无法运行，例如
```
idle
```
下无法读取 tree，或无法解析
```
run:
```
目标，则属于环境问题：修复后重新运行。失败的
launch:
同样计为
errored
，而且这是对应用本身的判定；如果应用已无法安装或启动，这正是该测试要捕获的回归，因此应报告，而不是重新运行。
完成前必须解决每个通过步骤产生的 warning，同时解决
```
e2e-finish-recording
```
记录的等待 warning。遵循实时等待与检查中的要求。对于 runner warning，
```
await: { idle: true }
```
会产生六种不同的 warning，因此应先确认具体类型。其中两种表示界面仍在移动；一种表示等待在 hold 期间超时，需要增大
```
timeout:
```
；一种表示 tree 始终为空；一种表示仅基于 UI tree 判定为稳定，即层级结构已保持稳定，但缺少成对的截图，此时应检查采集路径，而不是应用的渲染；最后一种表示步骤结束时没有任何正反证据，应检查界面、披露原因，并验证周围的验收检查使用的是稳定元素，而不是依赖静止状态。无选择器手势（没有
```
on:
```
的坐标
```
tap
```
/
```
long-press
```
/
```
swipe
```
，或
```
pinch
```
/
```
rotate
```
）产生的 warning 形式不同：tree 数据源中断导致步骤未达到稳定状态，因此手势是被盲发出去的，绿色结果仅表示手势已发送。应恢复 tree 数据源，通常是重新启动应用以加载 instrumentation，然后重新运行。只有应用完全不提供 tree 时才可接受该 warning，但这种应用本身也无法满足本契约。
立即使用同一个 runner 再次运行相同的 YAML，不要手动重置应用或账户数据。
任何失败、编辑、重新录制、基线更新或会改变状态的手动恢复操作之后，都要重置连续通过计数。通过
```
argent-create-e2e
```
修复，再次审计，并使用全新服务重新开始。

只有连续通过计数达到两次时才能结束。如果预期的 runner 不可用，则将验证报告为 blocked。如果产品行为失败，应保留强检查并报告该回归。永远不要为了让结果变绿而削弱检查。

记录所使用的 runner 和全新服务 setup。

6. Report

6. 报告

Report:

E2E test name, path, platform, and CLI 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.

报告应包括：

E2E 测试名称、路径、平台和 CLI 命令。
契约行与操作及检查之间的映射。
导航表。
基线 setup、结束状态恢复和已接受的数据依赖。
两次运行结果、runner、全新服务 setup 和已解决的 warning。
Snapshot 范围、已审阅的基线状态和差异容差。
坐标或原始手势例外。
仍需人工判断的事项或 blocker。