auto-e2e

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Auto E2E

自动化E2E测试

Version

版本

Current skill version:

1.1.0

For every future edit to this skill, bump the semantic version and update both:

```
VERSION
```
```
CHANGELOG.md
```

Use this bump policy:

patch: wording fixes, clarification, non-behavioral instruction tweaks
minor: backward-compatible new capabilities, flags, or output files
major: breaking changes to trigger shape, generated script contract, save paths, or runtime expectations

Read these references when needed:

references/recording-rules.md for the session workflow, queue handling, alias parsing, record mode, replay mode, and output contract.
references/replay.md for replay matching, expected-outcome checking, and mismatch handling.
references/variables.md for explicit variable detection and parameter generation.
references/versioning.md for semantic-version maintenance rules.
assets/package.json for the default workspace package file that must exist beside generated scripts.

当前Skill版本：

1.1.0

。

后续对本Skill的每一次编辑，都要升级语义化版本号并更新以下两处：

```
VERSION
```
```
CHANGELOG.md
```

版本升级规则：

patch：文字修正、说明补充、不改变行为的指令调整
minor：新增向后兼容的功能、标记或输出文件
major：对触发格式、生成脚本协议、保存路径或运行时预期的破坏性变更

必要时可参考以下文档：

references/recording-rules.md：会话流程、队列处理、别名解析、录制模式、回放模式及输出协议
references/replay.md：回放匹配、预期结果检查及不匹配处理
references/variables.md：显式变量检测及参数生成
references/versioning.md：语义化版本维护规则
assets/package.json：生成脚本旁必须存在的默认工作区package文件

Session workflow

会话流程

Start recording when the user says
```
/auto-e2e <url>
```
or
```
/aee <url>
```
or otherwise clearly asks to begin an auto-e2e recording for a specific page.
Detect optional flags from the same start message.
- If the user includes
```
record
```
  , enable record mode for this session.
- Examples that should enable record mode:
  - ```
  /auto-e2e https://example.com record
```
- ```
/auto-e2e record https://example.com
```
  - ```
  /aee https://example.com record
```
Also recognize replay mode when the user says
```
/auto-e2e replay <query>
```
or
```
/aee replay <query>
```
.
- In replay mode, search
```
auto-e2e/records/
```
  for the best matching prior record based on the natural-language query.
- If one record is a clear best match, load it, open its
```
targetUrl
```
  , and tell the user which record is being replayed.
- If there is significant ambiguity between multiple strong matches, show the top few likely records and ask the user to choose before proceeding.
Maintain session state in memory for the current conversation:
- ```
mode
```
  as
```
record
```
  or
```
replay
```
- ```
targetUrl
```
- ```
stepQueue[]
```
  in order
- ```
variables[]
```
  with
```
name
```
  ,
```
description
```
  ,
```
sampleValue
```
  , and optional
```
defaultValue
```
  only when the user explicitly asks for one
- ```
returnSpec
```
  if the user asks to return JSON data at the end
- ```
recordConversation
```
  boolean
- ```
conversationLog[]
```
  when record mode is enabled
- ```
scriptBasename
```
  to be decided only when recording ends
- ```
matchedRecord
```
  when replay mode is enabled
- ```
replayCursor
```
  for the current expected step index when replaying against a prior record
If record mode is enabled, append every recording-session user message and every agent reply to
```
conversationLog[]
```
using the raw original text. Do not summarize or normalize the message text in the saved record.
Interpret each later user message as one step unless the message is clearly a control message such as undo, cancel the last step, finish, abort, or replay confirmation.
Execute the step in the open browser first, then record the canonical script version of the step into
```
stepQueue
```
.
If the user asks to undo or cancel the last step, remove only the last recorded item from
```
stepQueue
```
. Do not change the browser. The user is responsible for restoring the page state manually.
In replay mode, after each executed step, compare the current outcome against the most relevant expected assistant reply from the matched record.
- If the current outcome is semantically consistent with the prior expected result, continue and advance
```
replayCursor
```
  .
- If the current outcome is inconsistent with the prior expected result, pause immediately and ask the user whether to continue, adjust the step, or stop.
When the user ends recording or replay re-recording, generate the final files inside the agent workspace
```
auto-e2e/
```
directory:

```
auto-e2e/package.json
```
```
auto-e2e/<content-summary-name>.mjs
```

auto-e2e/records/<content-summary-name>.json

only when

recordConversation

is true

After saving, return a concise summary including the skill version, mode, output path, chosen script filename, whether a record JSON was written, required variables, and how to run it.

当用户输入
```
/auto-e2e <url>
```
或
```
/aee <url>
```
，或明确要求开始针对特定页面的自动化E2E录制时，启动录制。
从启动消息中检测可选标记：
- 如果用户包含
```
record
```
  标记，为本会话启用录制模式。
- 应启用录制模式的示例：
  - ```
  /auto-e2e https://example.com record
```
- ```
/auto-e2e record https://example.com
```
  - ```
  /aee https://example.com record
```
当用户输入
```
/auto-e2e replay <query>
```
或
```
/aee replay <query>
```
时，识别为回放模式。
- 在回放模式下，根据自然语言查询在
```
auto-e2e/records/
```
  目录中查找最匹配的历史记录。
- 如果有一个明确的最佳匹配记录，加载它，打开其
```
targetUrl
```
  ，并告知用户正在回放哪条记录。
- 如果多个记录之间存在明显歧义，显示最可能的几条记录，让用户选择后再继续。
在内存中维护当前会话的状态：
- ```
mode
```
  ：
```
record
```
  或
```
replay
```
- ```
targetUrl
```
- ```
stepQueue[]
```
  ：步骤顺序队列
- ```
variables[]
```
  ：包含
```
name
```
  、
```
description
```
  、
```
sampleValue
```
  ，仅当用户明确要求时包含可选的
```
defaultValue
```
- ```
returnSpec
```
  ：用户要求在结束时返回JSON数据时的配置
- ```
recordConversation
```
  ：布尔值
- ```
conversationLog[]
```
  ：启用录制模式时的会话日志
- ```
scriptBasename
```
  ：仅在录制结束时确定
- ```
matchedRecord
```
  ：启用回放模式时匹配的历史记录
- ```
replayCursor
```
  ：回放时当前预期步骤的索引
如果启用录制模式，将录制会话中的每一条用户消息和Agent回复以原始文本形式追加到
```
conversationLog[]
```
中，保存记录时不要总结或标准化消息文本。
将后续每条用户消息视为一个步骤，除非消息是明确的控制指令，如撤销、取消上一步、完成、中止或回放确认。
先在打开的浏览器中执行步骤，然后将步骤的标准脚本版本记录到
```
stepQueue
```
中。
如果用户要求撤销或取消上一步，仅从
```
stepQueue
```
中移除最后一条记录的步骤，不要修改浏览器状态，用户需手动恢复页面状态。
在回放模式下，每执行完一个步骤后，将当前结果与匹配记录中最相关的预期Agent回复进行比较：
- 如果当前结果与之前的预期结果在语义上一致，则继续并推进
```
replayCursor
```
  。
- 如果当前结果与之前的预期结果不一致，立即暂停并询问用户是继续、调整步骤还是停止。

当用户结束录制或回放重录时，在Agent工作区的

auto-e2e/

目录中生成最终文件：

```
auto-e2e/package.json
```
```
auto-e2e/<内容摘要名称>.mjs
```

仅当

recordConversation

为true时，生成

auto-e2e/records/<内容摘要名称>.json

保存完成后，返回简洁的摘要，包括Skill版本、模式、输出路径、选择的脚本文件名、是否生成了记录JSON、所需变量以及运行方法。

Recording rules

录制规则

Treat the user's message as a browser action only when it clearly describes an intended action on the current page.
Supported first-version actions: click, hover, fill or clear inputs, select options, check or uncheck controls, keyboard actions including Enter, explicit waits for visible or hidden elements, and final data extraction for JSON output.
Prefer resilient locators in this order:
```
getByRole
```
,
```
getByLabel
```
,
```
getByPlaceholder
```
,
```
getByText
```
, then
```
locator(...)
```
only as a fallback.
Keep both a human-readable description and the exact generated Playwright code for each queued step, but the user does not need to see the code unless helpful.
After each mutating step, insert the default settle behavior:
1. wait until there are no network requests if possible;
2. then wait one additional second.
Implement settle behavior in generated code with a helper that gracefully falls back if
```
networkidle
```
never arrives.
Do not record pure conversation, clarifications, or status acknowledgements as browser steps.
In record mode, still save those non-step user and agent messages into
```
conversationLog[]
```
; only exclude browser-internal state dumps or tool traces.
In replay mode, use the matched record only as guidance and a verification baseline. The newly generated script must reflect what happened in the current run, not blindly copy the old steps if the user intentionally changed them.

仅当用户的消息明确描述了对当前页面的预期操作时，才将其视为浏览器操作。
第一版本支持的操作：点击、悬停、填写或清空输入框、选择选项、勾选或取消勾选控件、包括Enter在内的键盘操作、显式等待元素显示或隐藏、以及用于JSON输出的最终数据提取。
优先使用高稳定性定位器，顺序为：
```
getByRole
```
、
```
getByLabel
```
、
```
getByPlaceholder
```
、
```
getByText
```
，仅作为最后手段时使用
```
locator(...)
```
。
为每个排队的步骤同时保留人类可读的描述和精确生成的Playwright代码，但除非有帮助，否则无需向用户展示代码。
在每个会修改页面的步骤后，插入默认的稳定处理逻辑：
1. 尽可能等待无网络请求；
2. 然后再等待1秒。
在生成的代码中使用辅助函数实现稳定处理逻辑，如果
```
networkidle
```
状态始终无法达到，需优雅降级。
不要将纯对话、澄清或状态确认记录为浏览器步骤。
在录制模式下，仍需将这些非步骤类的用户和Agent消息保存到
```
conversationLog[]
```
中；仅排除浏览器内部状态转储或工具跟踪信息。
在回放模式下，仅将匹配的记录作为指导和验证基准。新生成的脚本必须反映当前运行的实际情况，如果用户有意更改步骤，不要盲目复制旧步骤。

Variable handling

变量处理

Only create variables when the user explicitly marks content as variable or clearly says it should become an argument. Examples:

“这个邮箱是变量，变量名 email，当前值是 demo@example.com”
“把收货人当成变量 recipientName，录制时先填张三”
“这一步里的搜索词后续会变，作为参数 searchKeyword，目前用手机”

When the user explicitly marks something as variable:

Require or infer a stable variable name in english lower camel case. If the user gives a Chinese name, translate it to a short english identifier.
Record the sample value because recording still needs a concrete value to drive the browser now.
Generate code that reads the runtime value from the single
```
params
```
object, for example
```
params.email
```
.
Never write the recorded sample value into the script as a default value unless the user explicitly says it should be used when the param is missing.
Add a runtime guard near the top of the script for every required variable that has no explicit default.
Keep all variables under one function parameter object. Never generate multiple positional arguments.

If the user explicitly asks to use the recorded value as a fallback, treat that variable as optional at runtime and emit the default in code. Otherwise treat the sample value as recording-only data that must not appear in the generated script beyond comments or metadata.

If the user does not clearly say something is a variable, keep it as a literal value in the script.

仅当用户明确标记内容为变量或明确说明其应作为参数时，才创建变量。示例：

“这个邮箱是变量，变量名 email，当前值是 demo@example.com”
“把收货人当成变量 recipientName，录制时先填张三”
“这一步里的搜索词后续会变，作为参数 searchKeyword，目前用手机”

当用户明确标记某内容为变量时：

要求或推断一个稳定的小驼峰式英文变量名。如果用户提供中文名称，将其转换为简短的英文标识符。
记录示例值，因为录制仍需要具体值来驱动当前浏览器操作。
生成从单个
```
params
```
对象中读取运行时值的代码，例如
```
params.email
```
。
除非用户明确说明参数缺失时应使用该值，否则不要将录制的示例值作为默认值写入脚本。
为每个无显式默认值的必填变量在脚本顶部附近添加运行时校验。
将所有变量放在一个函数参数对象中，切勿生成多个位置参数。

如果用户明确要求将录制的值作为回退值，则该变量在运行时为可选，并在代码中输出默认值。否则，将示例值视为仅用于录制的数据，除注释或元数据外，不得出现在生成的脚本中。

如果用户未明确说明某内容为变量，则将其作为字面量值保留在脚本中。

Final script and record contract

最终脚本和记录协议

Generate one single-file Playwright ESM script with these properties:

Filename: summarize the recorded workflow in english using lowercase words joined with hyphens. Make it specific but short, for example
```
login-search-order.mjs
```
or
```
open-dashboard-export-report.mjs
```
.
Location:
```
auto-e2e/<filename>.mjs
```
under the agent workspace.
Include a node shebang.
Default export exactly one async function receiving one object argument:

export default async function run(params = {}) {

Ensure
```
auto-e2e/package.json
```
exists and is compatible with the generated script. Use the bundled template in assets/package.json unless an equivalent file already exists.
The script must import Playwright from
```
playwright
```
, launch a browser, create a page, run all recorded steps, return the requested JSON object when the user asked for one, and always close the browser in
```
finally
```
.
If the user did not request data extraction, return a small JSON object describing success.
CLI mode must accept only one optional command-line argument: a JSON string representing the same
```
params
```
object.
In CLI mode, call the default-exported function and print the return value to stdout. If the return value is an object or array, print valid JSON.

If record mode is enabled, also write a JSON file to

auto-e2e/records/<script-basename>.json

with this shape:

json

{
  "skillVersion": "1.1.0",
  "targetUrl": "https://example.com",
  "scriptFile": "auto-e2e/login-search-order.mjs",
  "recordFile": "auto-e2e/records/login-search-order.json",
  "messages": [
    { "index": 1, "role": "user", "content": "/auto-e2e https://example.com record" },
    { "index": 2, "role": "assistant", "content": "已打开页面，等待下一步。" }
  ]
}

Rules for the record JSON:

Use the same basename as the generated script.
Preserve user original wording and agent reply text as-is.
Save only the recording-session conversation, from the start command through the final save confirmation for that session.
Store valid JSON only.

生成具有以下属性的单文件Playwright ESM脚本：

文件名：用英文小写单词连字符连接的形式总结录制的流程，要具体但简短，例如
```
login-search-order.mjs
```
或
```
open-dashboard-export-report.mjs
```
。
位置：Agent工作区下的
```
auto-e2e/<filename>.mjs
```
包含Node shebang
默认导出一个接收单个对象参数的异步函数：

export default async function run(params = {}) {

确保
```
auto-e2e/package.json
```
存在且与生成的脚本兼容，除非已有等效文件，否则使用assets/package.json中的捆绑模板。
脚本必须从
```
playwright
```
导入Playwright、启动浏览器、创建页面、运行所有录制的步骤、当用户要求时返回请求的JSON对象，并始终在
```
finally
```
中关闭浏览器。
如果用户未请求数据提取，返回一个描述成功的小型JSON对象。
CLI模式仅接受一个可选命令行参数：表示相同
```
params
```
对象的JSON字符串。
在CLI模式下，调用默认导出的函数并将返回值打印到标准输出。如果返回值是对象或数组，打印有效的JSON。

如果启用录制模式，还需将JSON文件写入

auto-e2e/records/<script-basename>.json

，格式如下：

json

{
  "skillVersion": "1.1.0",
  "targetUrl": "https://example.com",
  "scriptFile": "auto-e2e/login-search-order.mjs",
  "recordFile": "auto-e2e/records/login-search-order.json",
  "messages": [
    { "index": 1, "role": "user", "content": "/auto-e2e https://example.com record" },
    { "index": 2, "role": "assistant", "content": "已打开页面，等待下一步。" }
  ]
}

记录JSON的规则：

使用与生成脚本相同的基名。
完整保留用户原始措辞和Agent回复文本。
仅保存录制会话的对话，从启动命令到该会话的最终保存确认。
仅存储有效的JSON。

Replay contract

回放协议

When the user starts replay mode with

/auto-e2e replay <query>

/aee replay <query>

Search
```
auto-e2e/records/
```
for likely matches using:
- the natural-language replay query;
- record basename;
- target URL and hostname;
- notable user and assistant text from saved messages.
Load the matched record and use it to reconstruct the expected flow.
Re-record the flow in the live browser based on the current user instructions.
After each step, use the matched record's prior assistant reply as the main expectation for whether the behavior still looks correct.
Compare semantic outcomes, not exact wording. Prefer observed browser state over text similarity.
If the current result contradicts the prior expected result, stop and confirm with the user before continuing.
If the replay completes without unresolved mismatches, tell the user the verification re-recording is complete and then save the new script.

当用户使用

/auto-e2e replay <query>

或

/aee replay <query>

启动回放模式时：

使用以下信息在
```
auto-e2e/records/
```
中搜索可能的匹配项：
- 自然语言回放查询
- 记录基名
- 目标URL和主机名
- 保存消息中值得注意的用户和Agent文本
加载匹配的记录并使用它重建预期流程。
根据当前用户指令在真实浏览器中重新录制流程。
每完成一个步骤后，使用匹配记录中之前的Agent回复作为判断行为是否仍正常的主要依据。
比较语义结果，而非精确措辞，优先以观察到的浏览器状态为准，而非文本相似度。
如果当前结果与之前的预期结果矛盾，停止并在继续前与用户确认。
如果回放完成且无未解决的不匹配项，告知用户验证重录完成，然后保存新脚本。

Output checklist

输出检查清单

Before finishing, verify that the generated script:

uses only one
```
params
```
object for all variables;
includes required-variable validation for explicitly declared variables without explicit defaults;
does not leak recorded sample values into runtime defaults unless the user explicitly requested that behavior;
uses the default settle helper between steps;
writes valid ESM code runnable with Node;
writes or preserves
```
auto-e2e/package.json
```
;
saves the script with a summarized english hyphen-case filename.

Before finishing in record mode, also verify that the generated record file:

is saved under
```
auto-e2e/records/
```
;
uses the same basename as the script;
contains raw user and agent text from this recording session only;
includes the current skill version.

Before finishing in replay mode, also verify that:

the matched prior record was identified from
```
auto-e2e/records/
```
;
any mismatched step paused for user confirmation;
the final script reflects the current successful run, not stale prior code;
the completion message clearly states whether the replay matched cleanly or required user-confirmed divergence.

完成前，验证生成的脚本：

所有变量仅使用一个
```
params
```
对象；
对显式声明且无默认值的变量包含必填变量校验；
除非用户明确要求，否则不会将录制的示例值泄露到运行时默认值中；
在步骤之间使用默认的稳定处理辅助函数；
编写可通过Node运行的有效ESM代码；
写入或保留
```
auto-e2e/package.json
```
；
使用英文连字符格式的摘要文件名保存脚本。

在录制模式下完成前，还需验证生成的记录文件：

保存到
```
auto-e2e/records/
```
目录下；
使用与脚本相同的基名；
仅包含本次录制会话的原始用户和Agent文本；
包含当前Skill版本。

在回放模式下完成前，还需验证：

从
```
auto-e2e/records/
```
中识别出匹配的历史记录；
任何不匹配的步骤都已暂停并等待用户确认；
最终脚本反映当前成功运行的情况，而非过时的旧代码；
完成消息明确说明回放是否完全匹配，或是否需要用户确认的差异。