argent-create-e2e

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create an Argent e2e test

创建 Argent e2e 测试

An Argent e2e test is a replayable sequence in

.argent/e2e/<name>.yaml

(

.argent/flows/

is still read).

For a saved QA test case, ticket, or acceptance criterion, load

argent-qa-e2e

first. It adds deterministic setup, acceptance evidence, and two-pass proof.

Argent e2e 测试是一段可回放的交互序列，存储在

.argent/e2e/<name>.yaml

中（仍会读取

.argent/flows/

）。

对于已保存的 QA 测试用例、工单或验收标准，请先加载

argent-qa-e2e

。它会提供确定性的环境设置、验收证据和两次连续通过的证明。

Read the relevant reference

阅读相关参考文档

Before creating or changing an e2e test, read Live authoring completely.
When polishing, composing, or manually reviewing YAML, read E2E YAML. For Vega, read its platform limits before recording remote or keyboard tools.
E2E tests run on physical iPhones (an iOS
```
list-devices
```
entry with kind
```
"device"
```
), but replay never auto-binds one, even when no simulator is booted: pass the phone's udid as
```
device
```
(CLI
```
--device
```
), and only a
```
connected
```
phone can run.
```
pinch
```
/
```
rotate
```
steps fail there like the live tools. On hardware the runner tree is the
```
describe
```
tree: same ids and roles, no UIView hierarchy. See
```
argent-ios-device-interact
```
for the hardware contract.
On capture warnings, raw coordinates, unavailable trees, mistimed transitions, overlays, or replay failures, read Reliability and recovery.

在创建或修改 e2e 测试之前，请完整阅读实时编写。
在优化、组合或手动审查 YAML 时，请阅读 E2E YAML。对于 Vega，在录制远程或键盘工具之前，请先阅读其平台限制。
E2E 测试在实体 iPhone 上运行（iOS
```
list-devices
```
条目中的 kind 为
```
"device"
```
），但回放时绝不会自动绑定设备，即使没有启动模拟器：将手机的 udid 作为
```
device
```
传入（CLI 参数为
```
--device
```
），并且只有处于
```
connected
```
状态的手机才能运行。在此类设备上，
```
pinch
```
/
```
rotate
```
步骤会像实时工具一样失败。在硬件设备上，运行器树就是
```
describe
```
树：具有相同的 ids 和 roles，但不存在 UIView 层级。请参阅
```
argent-ios-device-interact
```
了解硬件契约。
遇到采集警告、原始坐标、不可用的树、时机不当的转场、遮挡层或回放失败时，请阅读可靠性与恢复。

Non-negotiable rules

不可违反的规则

Record the first walkthrough. Start the recorder before the first launch or in-app action. Do not reconstruct a rehearsed path.
Record checks when their states appear. Record
```
await-ui-element
```
live, then convert it during polish. An echo records intent or diagnostic context, not app behavior or a verdict. A screenshot is human evidence, not an executable verdict. For absence, record the same selector as
```
visible
```
, perform the removing action, then record it as
```
hidden
```
.
Use semantic targets. Prefer a strict id, then stable text or an accessibility label. Use
```
scroll-to
```
for off-screen elements. Resolve every raw-point warning immediately through the coordinate fallback gate.
Prove every screen change. Record a destination-only identity check. During polish, follow it with
```
await: { idle: true }
```
. Stillness does not prove identity, and
```
idle
```
can pass with a warning.
Polish only executed behavior. Convert recorded steps without changing their meaning. Record any missing action or structural check live. The only unrecorded insertions are a planned
```
snapshot:
```
, a navigation
```
await: { idle: true }
```
, and the documented Chromium packaging
```
launch:
```
.
Use scripts only when the user requests them. Read E2E YAML: Local scripts, then record each script with
```
e2e-add-script
```
.
Replay the final YAML end to end. A normal e2e test needs one uninterrupted full pass.
```
argent-qa-e2e
```
requires two consecutive passes.

录制首次走查。 在首次启动或执行应用内操作之前启动录制器。不要根据已经排练过的路径重新构建操作。
在检查状态出现时进行录制。 实时录制
```
await-ui-element
```
，然后在优化阶段将其转换。
```
echo
```
记录的是意图或诊断上下文，而不是应用行为或判定结果。截图是人类查看的证据，而不是可执行的判定。对于元素不存在的情况，先将同一选择器录制为
```
visible
```
，执行移除操作，然后将其录制为
```
hidden
```
。
使用语义目标。 优先使用严格的 id，其次使用稳定的文本或 accessibility label。对于屏幕外的元素，使用
```
scroll-to
```
。出现原始坐标警告时，必须立即通过坐标回退门禁解决。
证明每一次屏幕变化。 录制仅针对目标页面的身份检查。在优化阶段，在其后添加
```
await: { idle: true }
```
。静止状态不能证明身份，并且
```
idle
```
可能会在带有警告的情况下通过。
仅优化已执行的行为。 转换已录制的步骤时，不得改变其含义。任何缺失的操作或结构检查都必须实时录制。唯一允许直接插入且未录制的项目包括计划中的
```
snapshot:
```
、导航
```
await: { idle: true }
```
，以及文档中规定的 Chromium 打包
```
launch:
```
。
仅在用户明确要求时使用脚本。 请先阅读 E2E YAML：本地脚本，然后使用
```
e2e-add-script
```
录制每个脚本。
端到端回放最终的 YAML。 普通 e2e 测试需要一次不中断的完整通过。
```
argent-qa-e2e
```
要求连续两次通过。

Stable selectors

稳定选择器

A stable selector is fixed by app code and survives account, data, time, count, order, and every locale and environment the e2e test supports. Prefer ids such as

settings-screen

. Do not gate on values such as

Today

Item 4

, usernames, counters, or timestamps.

稳定选择器由应用代码固定，不受账户、数据、时间、数量、顺序以及 e2e 测试支持的所有语言区域和环境影响。优先使用诸如

settings-screen

这样的 id。不要依赖

Today

、

Item 4

、用户名、计数器或时间戳等值。

YAML-only selector scopes

仅限 YAML 的选择器作用域

During polish, use

within

after

, and

next

to disambiguate repeated elements. Read E2E YAML: Relational scopes for their frame-based semantics and failure cases.

在优化阶段，使用

within

、

after

和

next

消除重复元素的歧义。请阅读 E2E YAML：关系作用域，了解其基于帧的语义和失败场景。

Workflow

工作流

Choose the e2e test type:
- standalone: the first step that is not
```
echo:
```
  or
```
script:
```
  is
```
launch:
```
  . The test controls process start.
- fragment: there is no leading launch. Declare a precise
```
executionPrerequisite
```
  .
Follow Live authoring: start, record one verified step at a time, finish, polish, audit, and replay.
Report the file, replay command, result, prerequisite or side effects, and every coordinate or raw-gesture exception.

选择 e2e 测试类型：
- standalone： 第一个不是
```
echo:
```
  或
```
script:
```
  的步骤是
```
launch:
```
  。测试负责控制进程启动。
- fragment： 开头没有
```
launch:
```
  。需要声明精确的
```
executionPrerequisite
```
  。
按照实时编写执行：启动、每次录制并验证一个步骤、结束、优化、审查和回放。
报告文件、回放命令、结果、前置条件或副作用，以及每一个坐标或原始手势例外。

Proactive recording

主动录制

Before repeating three or more interactions, tell the user and start a recording. Record that run and replay it afterward. A completed path cannot be recorded retroactively.

在重复三次或以上交互之前，告知用户并开始录制。录制该次运行，随后进行回放。已完成的操作路径无法事后补录。

Repair

修复

When replay fails, follow Reliability and recovery. Inspect the first divergence, correct the smallest justified unit, audit, and replay the full e2e test. Stop after two unsuccessful correction cycles. Never weaken a requested check to obtain a pass.

回放失败时，请遵循可靠性与恢复。检查首次出现偏差的位置，修正最小且有充分依据的单元，进行审查，并回放完整的 e2e 测试。两次修正尝试均失败后应停止。绝不能为了通过测试而削弱用户要求的检查。