accelint-ac-to-playwright

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AC To Playwright

AC 转 Playwright

MANDATORY - READ ENTIRE FILE: Before processing ANY acceptance criteria, you MUST read

references/acceptance-criteria.md

(~175 lines) completely from start to finish. NEVER set any range limits when reading this file. It is the authoritative source for AC writing rules and mappings.

Note on test-hooks.md: Load

references/test-hooks.md

when converting AC → JSON plans or when running Assessment mode — it contains the controlled vocabulary for area/component/intent target naming patterns. Do NOT load when converting plans → tests (translation script handles this automatically).

强制要求 - 通读全文：在处理任何验收标准（AC）之前，你必须完整通读

references/acceptance-criteria.md

（约175行）。读取此文件时绝不能设置任何范围限制。它是AC编写规则和映射关系的权威来源。

关于test-hooks.md的说明：在将AC转换为JSON计划或运行评估模式时，加载

references/test-hooks.md

——它包含了区域/组件/意图目标命名模式的受控词汇表。在将计划转换为测试用例时请勿加载（转换脚本会自动处理此操作）。

Intent Detection

意图检测

The skill supports two modes based on user phrasing:

Assessment mode (triggers on):

"review these AC"
"evaluate these AC"
"check if these AC are ready"
"can these AC be converted as-is"
"are these AC automation-ready"
"assess these acceptance criteria"

Full conversion mode (triggers on):

"convert these AC"
"generate tests from AC"
"turn AC into Playwright tests"
"create test automation"

Assessment mode analyzes AC text only (no artifact generation). Full conversion mode generates plans and tests.

本技能根据用户的表述支持两种模式：

评估模式（触发关键词）：

"评审这些AC"
"评估这些AC"
"检查这些AC是否已准备好"
"这些AC是否可直接转换"
"这些AC是否适合自动化"
"评估这些验收标准"

完整转换模式（触发关键词）：

"转换这些AC"
"根据AC生成测试用例"
"将AC转换为Playwright测试用例"
"创建测试自动化"

评估模式仅分析AC文本（不生成任何产物）。完整转换模式会生成测试计划和测试用例。

Assessment Workflow

评估工作流

Detect intent: User asks to review/evaluate/assess/check AC readiness.
Prepare for the task:

Read

references/acceptance-criteria.md

and

references/test-hooks.md

Work one input file at a time.

Analyze AC text against all conversion requirements:
- Structure & Format:
  - Bullet format: proper
```
- 
```
    markers for each AC
  - Gherkin format: valid Feature/Scenario/Examples/Given/When/Then/tags structure
  - Step ordering: all Givens → all Whens → all Thens (no mixing within a scenario)
- Targets (semantic validation):
  - Every action specifies a target
  - Target meets the area/component/intent pattern (all three parts present)
  - Area matches controlled vocabulary from
```
test-hooks.md
```
    (nav, header, footer, form, drawer, card, toast, modal, table, page, area)
  - Component matches controlled vocabulary (button, link, input, dropdown, checkbox, radio, text, div, component)
  - Intent is present
- Actions:
  - Verbs are recognized and mappable to Playwright actions (click, fill, select, drag)
  - No vague verbs (interact, use, hover without x/y coordinates)
  - Fill/select actions have quoted literal values (not "a valid email" or "any value")
- Expected Outcomes:
  - Explicitly stated (not implied or inferred)
  - Measurable (specific text content, element, or state)
  - Visibility changes use trigger words (appears, shows, hides, visible, see)
Report results:
- If issues found: Report "❌ AC are not conversion-ready" with detailed issue list (see output format below)
- If no issues: Report "✓ AC are conversion-ready" with validated checklist
- Do NOT generate any files (no JSON plans, no test files)
- Report results for all input files - do not stop Assessment mode after a single failure to ensure all issues are surfaced to the user at once.

检测意图：用户要求评审/评估/检查AC的自动化就绪情况。
任务准备：

读取

references/acceptance-criteria.md

和

references/test-hooks.md

。

一次处理一个输入文件。

对照所有转换要求分析AC文本：
- 结构与格式：
  - 项目符号格式：每个AC都有正确的
```
- 
```
    标记
  - Gherkin格式：有效的Feature/Scenario/Examples/Given/When/Then/标签结构
  - 步骤顺序：所有Given步骤在前，然后是When步骤，最后是Then步骤（场景内不得混合）
- 目标（语义验证）：
  - 每个操作都指定了目标
  - 目标符合区域/组件/意图的模式（三个部分均存在）
  - 区域与
```
test-hooks.md
```
    中的受控词汇表匹配（nav、header、footer、form、drawer、card、toast、modal、table、page、area）
  - 组件与受控词汇表匹配（button、link、input、dropdown、checkbox、radio、text、div、component）
  - 意图已明确
- 操作：
  - 动词可被识别并映射到Playwright操作（click、fill、select、drag）
  - 无模糊动词（如interact、use、未指定坐标的hover）
  - Fill/select操作使用带引号的字面量值（而非"有效的邮箱"或"任意值"）
- 预期结果：
  - 明确陈述（而非隐含或推断）
  - 可衡量（特定文本内容、元素或状态）
  - 可见性变化使用触发词（appears、shows、hides、visible、see）
报告结果：
- 若发现问题：报告"❌ AC未准备好进行转换"并附上详细问题列表（见下方输出格式）
- 若无问题：报告"✓ AC已准备好进行转换"并附上验证通过的检查清单
- 不得生成任何文件（无JSON计划，无测试文件）
- 报告所有输入文件的结果——即使单个文件失败，也不要停止评估模式，确保所有问题一次性呈现给用户。

Conversion Workflow

转换工作流

Detect intent: User asks to generate/convert/write tests from AC files.
Run Assessment mode:

Run Assessment mode against all input files and report pass/fail result.
If Assessment mode reported any failures across all files, STOP. Do not proceed with the rest of Conversion mode.

Prepare for the task:

Require the user to explicitly provide output directories for plans, tests, and summaries before writing any files.
Read
```
references/acceptance-criteria.md
```
.
Work one input file at a time. Do not parallelize so that errors in one file's workflow do not affect other files' workflows.
Derive suite name, test names, startUrl, steps, targets, tags, and source metadata per the rules below.

JSON test plan:

Build a JSON test plan that conforms to
```
references/plan-schema.ts
```
.
Validate the test plan and report results.
If validation failed, stop. Do not write the plan. Skip the rest of these steps for the current input file and move on to the next input file.
If validation passed, write the plan to the user-specified output directory:
```
<plans-output-dir>/<suite-slug>.json
```
.

Translate the plan to tests:

Once the plan file is written, translate the plan with
```
scripts/translate-plan-to-tests.ts
```
.
Write the test suite file to the user-specified output directory:
```
<tests-output-dir>/<suite-slug>.spec.ts
```
.
Append a summary entry to the batch JSON file in the user-specified summary directory (one batch file per run).

Next steps:

Work on the next input file, if any remain.
After all files are processed, ask the user if they would like a Playwright config template. If yes, copy
```
skills/accelint-ac-to-playwright/assets/templates/playwright.config.ts
```
into the user‑specified summaries location.

检测意图：用户要求根据AC文件生成/转换/编写测试用例。
运行评估模式：

对所有输入文件运行评估模式并报告通过/失败结果。
若评估模式报告任何文件失败，停止操作。不得继续执行转换模式的后续步骤。

任务准备：

要求用户明确提供计划、测试用例和摘要的输出目录，然后再写入任何文件。
读取
```
references/acceptance-criteria.md
```
。
一次处理一个输入文件。请勿并行处理，避免单个文件工作流中的错误影响其他文件的工作流。
根据以下规则推导测试套件名称、测试用例名称、startUrl、步骤、目标、标签和源元数据。

JSON测试计划：

构建符合
```
references/plan-schema.ts
```
规范的JSON测试计划。
验证测试计划并报告结果。
若验证失败，停止操作。不要写入计划文件。跳过当前输入文件的后续步骤，处理下一个输入文件。
若验证通过，将计划写入用户指定的输出目录：
```
<plans-output-dir>/<suite-slug>.json
```
。

将计划转换为测试用例：

写入计划文件后，使用
```
scripts/translate-plan-to-tests.ts
```
转换计划。
将测试套件文件写入用户指定的输出目录：
```
<tests-output-dir>/<suite-slug>.spec.ts
```
。
将摘要条目追加到用户指定摘要目录中的批量JSON文件中（每次运行对应一个批量文件）。

后续步骤：

若有剩余输入文件，处理下一个。
所有文件处理完成后，询问用户是否需要Playwright配置模板。若需要，将
```
skills/accelint-ac-to-playwright/assets/templates/playwright.config.ts
```
复制到用户指定的摘要位置。

Recognition Patterns

识别模式

Before processing AC, identify these quality signals:

Good AC (can process directly):

Check	Question	If NO → Action
Targets	Does every action specify area.component.intent?	Ask user to clarify which specific element
Values	Are all fill/select values quoted literals?	Ask user for exact values to use
Outcomes	Are expectations measurable (specific text/element/state)?	Ask user what exactly to verify

Bad patterns (ask the user questions):

"interact with" (and other similar language) → too vague, agent can't map to Playwright action
Dropdown: "select the first option" → fails, needs exact text
Always quote exact literals:
```
'test@example.com'
```
not "a valid email"

The above table directs you to ask for clarifications because guessing creates tests that fail unpredictably.

处理AC之前，先识别以下质量信号：

合格的AC（可直接处理）：

检查项	问题	若为否 → 操作
目标	每个操作是否都指定了area.component.intent？	请用户明确具体元素
值	所有fill/select的值是否为带引号的字面量？	请用户提供要使用的精确值
预期结果	预期结果是否可衡量（特定文本/元素/状态）？	请用户明确具体要验证的内容

不合格模式（需向用户确认）：

"与...交互"（及类似表述）→ 过于模糊，无法映射到Playwright操作
下拉框："选择第一个选项" → 不允许，需要精确文本
始终使用带引号的精确字面量：
```
'test@example.com'
```
而非"有效的邮箱"

上述表格指导你向用户确认信息，因为猜测会导致测试用例不可预测地失败。

Naming Transformations

命名转换

Input to output mapping: One AC file → one suite → one plan file (

<plans-dir>/<suite-slug>.json

) → one test file

```
.md
```
bullet-style: each
```
- 
```
bullet = one test
```
.feature
```
Gherkin: each Scenario = one test; each Examples row in Scenario Outline = one test

Input	Suite Name	Test Name	Output Slug
`.feature`	`Feature:` text → lowercase → capitalize first	Scenario text (lowercase, ~64 char limit) + `(params)` for Scenario Outlines	suite name → lowercase, spaces to dashes
`.md`	filename → lowercase → dashes to spaces → capitalize first	Summarize bullet intent (present tense, lowercase, ~64 char)	suite name → lowercase, spaces to dashes

Scenario Outline parameters: Use shortest left-to-right column combo that uniquely identifies each row, joined with

Example:

Examples:
  | username | password | message       |
  | user1    | pass1    | Welcome user1 |
  | user2    | pass2    | Welcome user2 |

Appends

 (user1/pass1)

and

 (user2/pass2)

respectively.

输入到输出的映射：一个AC文件 → 一个测试套件 → 一个计划文件（

<plans-dir>/<suite-slug>.json

） → 一个测试文件

```
.md
```
项目符号格式：每个
```
- 
```
项目符号对应一个测试用例
```
.feature
```
Gherkin格式：每个Scenario对应一个测试用例；Scenario Outline中的每个Examples行对应一个测试用例

输入	测试套件名称	测试用例名称	输出Slug
`.feature`	`Feature:` 文本 → 小写 → 首字母大写	Scenario文本（小写，约64字符限制） + 对于Scenario Outline添加 `(params)`	测试套件名称 → 小写，空格替换为连字符
`.md`	文件名 → 小写 → 连字符替换为空格 → 首字母大写	总结项目符号的意图（现在时，小写，约64字符）	测试套件名称 → 小写，空格替换为连字符

Scenario Outline参数：使用从左到右最短的列组合来唯一标识每一行，用

连接。

示例：

Examples:
  | username | password | message       |
  | user1    | pass1    | Welcome user1 |
  | user2    | pass2    | Welcome user2 |

分别追加

 (user1/pass1)

和

 (user2/pass2)

。

Tags (Gherkin only)

标签（仅Gherkin）

Feature-level tags -> suite tags.
Scenario-level tags -> test tags.
Do not include suite tags in test tags; drop duplicates at the test level.
If no test tags remain, omit tags field for that test.
Tag values include the leading '@'.

Feature级别的标签 → 测试套件标签。
Scenario级别的标签 → 测试用例标签。
不要在测试用例标签中包含测试套件标签；在测试用例级别去除重复标签。
若测试用例无剩余标签，省略该测试用例的tags字段。
标签值包含前导的
```
@
```
。

Source metadata

源元数据

Always include a source object at suite level.
If AC file is inside a git repo: repo = repo name (folder containing
```
.git
```
), path = repo-relative path.
If AC file is not inside a git repo: repo =
```
external
```
, path = file basename only.
Do not store absolute paths.

测试套件级别始终包含source对象。
若AC文件在git仓库内：repo = 仓库名称（包含
```
.git
```
的文件夹），path = 仓库相对路径。
若AC文件不在git仓库内：repo =
```
external
```
，path = 仅文件名。
不得存储绝对路径。

Output Rules

输出规则

Suite-level fields

测试套件级别字段

Top-level field order: suiteName, tags (if any), source, tests.

顶级字段顺序：suiteName、tags（若有）、source、tests。

Test-level fields

测试用例级别字段

Start URL: always default to '/' unless the user provides an explicit starting page in a given AC per
```
references/acceptance-criteria.md
```
.
Steps: use only schema actions (but do not use
```
goto
```
) and preserve the order in the bullet text or in the Gherkin steps.
- Keyboard modifier combinations: When AC describes pressing a key combination (e.g., "press Shift+g", "press Control+Enter"), translate it into a three-step sequence:
  1. ```
  keyDown
```
  with the modifier key (e.g.,
```
  Shift
```
  ,
```
  Control
```
  , or app-specific modifier
```
  a
```
  )
2. ```
press
```
    with the non-modifier key (e.g.,
```
g
```
    ,
```
Enter
```
    )
  3. ```
  keyUp
```
  with the same modifier key
- Valid modifiers for
```
  keyDown
```
  /
```
  keyUp
```
  :
```
  Shift
```
  ,
```
  Control
```
  ,
```
  a
```
  (app-specific)
- The
```
  press
```
  action only accepts single unmodified keys and should never receive combination syntax like
```
  Shift+g
```
Assertions:
- If navigation is triggered, add
```
expectUrl
```
  using the Start URL mapping.
- For visibility changes (e.g., visible/appears/shows/hides and similar wording), add
```
expectNotVisible
```
  immediately before the action and
```
expectVisible
```
  immediately after (or vice versa as appropriate).
- Only add
```
expectText
```
  /
```
expectVisible
```
  /
```
expectNotVisible
```
  when the AC explicitly names text or visibility.
- Do not invent assertions. NEVER infer unstated information. Required fields that MUST be explicit (not inferred):
  - target: Must include area + component + intent
  - value: Must be quoted literal for fills
  - expected outcomes: Must include verifiable element/text

起始URL：默认始终为
```
'/'
```
，除非用户在AC中明确指定了起始页面（参考
```
references/acceptance-criteria.md
```
）。
步骤：仅使用 schema 中定义的操作（不得使用
```
goto
```
），并保留项目符号文本或Gherkin步骤中的顺序。
- 键盘组合键：当AC描述按下组合键时（例如"按Shift+g"、"按Control+Enter"），将其转换为三步序列：
  1. ```
  keyDown
```
  按下修饰键（例如
```
  Shift
```
  、
```
  Control
```
  或应用特定修饰键
```
  a
```
  ）
2. ```
press
```
    按下非修饰键（例如
```
g
```
    、
```
Enter
```
    ）
  3. ```
  keyUp
```
  释放相同的修饰键
- ```
keyDown
```
    /
```
keyUp
```
    支持的修饰键：
```
Shift
```
    、
```
Control
```
    、
```
a
```
    （应用特定）
  - ```
  press
```
  操作仅接受单个无修饰的键，绝不能使用
```
  Shift+g
```
  这样的组合语法
断言：
- 若触发导航，添加
```
expectUrl
```
  并使用起始URL映射。
- 对于可见性变化（例如visible/appears/shows/hides及类似表述），在操作前立即添加
```
expectNotVisible
```
  ，操作后立即添加
```
expectVisible
```
  （或根据情况反之）。
- 仅当AC明确提及文本或可见性时，才添加
```
expectText
```
  /
```
expectVisible
```
  /
```
expectNotVisible
```
  。
- 不得自行添加断言。绝不能推断未明确说明的信息。必须明确指定的必填字段（不得推断）：
  - target：必须包含area + component + intent
  - value：fill操作必须使用带引号的字面量
  - 预期结果：必须包含可验证的元素/文本

Resources

资源

```
scripts/plan-schema.ts
```
— schema and validation logic to consult when generating plans.
```
scripts/cli/validate-plan.ts
```
— validator script for JSON plans (run via
```
npx validate-plan
```
after build).
```
scripts/translate-plan-to-tests.ts
```
— converts a validated plan to a Playwright spec.
```
scripts/cli/generate-tests.ts
```
— CLI wrapper for reading, validating, and writing spec files.

```
scripts/plan-schema.ts
```
— 生成计划时参考的schema和验证逻辑。
```
scripts/cli/validate-plan.ts
```
— JSON计划的验证脚本（构建后通过
```
npx validate-plan
```
运行）。
```
scripts/translate-plan-to-tests.ts
```
— 将验证通过的计划转换为Playwright测试规范。
```
scripts/cli/generate-tests.ts
```
— 用于读取、验证和写入测试规范文件的CLI包装器。

Validation and Retry Protocol

验证与重试协议

Use

npx validate-plan path/to/plan.json

to validate a plan against

references/plan-schema.ts

(after build).

Maximum attempts: 2 total (initial + 1 correction)

Attempt 1: Generate JSON → validate

Pass → proceed to write file
Fail → go to Attempt 2

Attempt 2: Read validation error → fix ONE specific issue → re-validate

Pass → proceed to write file
Fail → STOP, report error to user

NEVER:

Make multiple changes at once (fix one thing, validate, repeat)
Retry by rephrasing same JSON differently
Guess at schema requirements if error is unclear

使用

npx validate-plan path/to/plan.json

来对照

references/plan-schema.ts

验证计划（构建后）。

最大尝试次数：共2次（初始尝试 + 1次修正）

第一次尝试：生成JSON → 验证

通过 → 继续写入文件
失败 → 进行第二次尝试

第二次尝试：读取验证错误 → 修复一个特定问题 → 重新验证

通过 → 继续写入文件
失败 → 停止操作，向用户报告错误

绝对禁止：

同时进行多处修改（修复一个问题，验证，重复此过程）
通过重新表述相同JSON来重试
若错误不明确，猜测schema要求

Error Recovery

错误恢复

Error Type	Diagnostic Question	Common Causes	Fix Strategy
Schema validation fails	What field does error message name?	Wrong field order, missing required field, extra field not in schema, incorrect field type	Check schema for exact field names and order; compare your JSON structure to schema requirements
Target naming invalid	Does target match `area.component.intent` ?	Wrong pattern structure, invalid keywords from controlled lists, missing dots	Review `test-hooks.md` for controlled vocabulary (area: nav/header/footer/etc, component: button/link/input/etc); use fallback keywords (last in each list) if AC term doesn't match
Translation script errors	Which action/assertion caused failure?	Unsupported action type, malformed target selector, missing required field in step	Verify action is in allowed list (click/fill/select); check target has all three parts; ensure step has target and any required fields (e.g., fill needs value)
Validation passes but tests fail	Do test hooks match actual page elements?	Target selectors don't match DOM, wrong start URL, timing issues	Ask user to verify page structure matches expected targets; check if startUrl needs adjustment; consider if dynamic content needs wait conditions
Multiple validation failures after fixes	Did first fix break something else?	Making multiple speculative changes, misunderstanding schema requirements	Stop after 2 attempts; report specific schema violations to user; ask if AC has ambiguities or if schema has changed

错误类型	诊断问题	常见原因	修复策略
Schema验证失败	错误消息指向哪个字段？	字段顺序错误、缺少必填字段、存在schema中未定义的额外字段、字段类型不正确	检查schema中的精确字段名称和顺序；将你的JSON结构与schema要求进行对比
目标命名无效	目标是否符合 `area.component.intent` 模式？	模式结构错误、使用了受控列表外的无效关键词、缺少点号	查看 `test-hooks.md` 中的受控词汇表（area：nav/header/footer等，component：button/link/input等）；若AC术语不匹配，使用列表中的备用关键词
转换脚本错误	哪个操作/断言导致失败？	不支持的操作类型、目标选择器格式错误、步骤中缺少必填字段	验证操作是否在允许列表中（click/fill/select）；检查目标是否包含三个部分；确保步骤包含目标及所有必填字段（例如fill操作需要value）
验证通过但测试失败	测试钩子是否与实际页面元素匹配？	目标选择器与DOM不匹配、起始URL错误、时序问题	请用户验证页面结构是否与预期目标匹配；检查startUrl是否需要调整；考虑动态内容是否需要等待条件
修复后仍存在多个验证失败	第一次修复是否破坏了其他内容？	进行了多处推测性修改、误解了schema要求	2次尝试后停止；向用户报告具体的schema违规情况；询问AC是否存在歧义或schema是否已更改

NEVER Do

绝对禁止操作

NEVER generate artifacts in assessment mode — when the user asks to review/evaluate/assess AC, analyze the AC text only and provide the formatted report. Do not generate JSON plans or test files. Do not assume they want full conversion.
NEVER skip controlled vocabulary checks in assessment — verify that area and component keywords in targets match the lists in
```
test-hooks.md
```
.
NEVER use
goto
action in steps — tests start at
```
startUrl
```
, navigation happens via clicks or fills that trigger page changes. Using goto mid-test breaks Playwright's navigation lifecycle and causes race conditions where assertions run before the page is ready, leading to flaky tests that pass locally but fail in CI.
NEVER use
doubleClick
for element interactions —
```
doubleClick
```
is only for coordinate-based double-clicks (x,y positions). For double-clicking elements, use the element-based
```
click
```
action twice in sequence. Only use
```
doubleClick
```
when AC explicitly specifies coordinates.
NEVER use
mouseClick
for element interactions —
```
mouseClick
```
is only for coordinate-based clicks (x,y positions). For clicking elements, always use
```
click
```
with test IDs. Only use
```
mouseClick
```
when AC explicitly specifies coordinates.
NEVER use
mouseMove
without a follow-up action —
```
mouseMove
```
positions the cursor but doesn't interact with anything. It should only be used before actions like
```
mouseDown
```
,
```
mouseUp
```
,
```
mouseClick
```
, or when AC explicitly requires moving to specific coordinates before other mouse operations.
NEVER use
mouseDown
or
mouseUp
without
mouseMove
first — these actions press/release buttons at the current cursor position. Always use
```
mouseMove
```
to position the cursor before
```
mouseDown
```
/
```
mouseUp
```
, otherwise the position is unpredictable.
NEVER invent assertions — only add
```
expectText
```
,
```
expectVisible
```
,
```
expectNotVisible
```
when AC explicitly states expected outcomes (exception:
```
expectUrl
```
for navigation, visibility pairs for show/hide actions)
NEVER store absolute file paths in source metadata — the expected convention is to use repo-relative paths for git repos, basename only for external files
NEVER assume targets or values — if AC says "click the button" without identifying which button, ask for clarification rather than guessing. Generic targets like
```
button.generic
```
bypass the controlled vocabulary system and create tests that break because they match multiple elements unpredictably.
NEVER skip validation — even if JSON looks correct, always run
```
npx validate-plan
```
before writing files to catch errors and reduce incorrect artifact cleanup
NEVER reuse existing plans or tests — this has caused problems in the past with changes being lost, so always regenerate all steps from AC source to ensure accuracy
NEVER write a plan file without validating first — validation catches structural errors; writing invalid plans creates broken artifacts requiring manual cleanup
NEVER process multiple steps of one file in parallel — complete the full pipeline (AC → plan → test → summary) for each file before moving to the next to avoid partial artifacts and state confusion
NEVER take shortcuts. - agents have gone off the rails when trying to define their own shortcuts, so when triggered you must always run the full workflow.

绝不能在评估模式下生成产物 — 当用户要求评审/评估/检查AC时，仅分析AC文本并提供格式化报告。不得生成JSON计划或测试文件。不得假设用户需要完整转换。
绝不能在评估模式下跳过受控词汇表检查 — 验证目标中的area和component关键词是否与
```
test-hooks.md
```
中的列表匹配。
绝不能在步骤中使用
goto
操作 — 测试从
```
startUrl
```
开始，导航通过触发页面变化的点击或fill操作实现。在测试中途使用goto会破坏Playwright的导航生命周期，导致断言在页面准备好之前运行，从而产生在本地通过但在CI中失败的不稳定测试用例。
绝不能使用
doubleClick
进行元素交互 —
```
doubleClick
```
仅适用于基于坐标的双击（x,y位置）。若要双击元素，使用基于元素的
```
click
```
操作连续点击两次。仅当AC明确指定坐标时，才使用
```
doubleClick
```
。
绝不能使用
mouseClick
进行元素交互 —
```
mouseClick
```
仅适用于基于坐标的点击（x,y位置）。若要点击元素，始终使用带测试ID的
```
click
```
操作。仅当AC明确指定坐标时，才使用
```
mouseClick
```
。
绝不能在没有后续操作的情况下使用
mouseMove
—
```
mouseMove
```
仅定位光标，不进行任何交互。仅在
```
mouseDown
```
、
```
mouseUp
```
、
```
mouseClick
```
等操作之前使用，或当AC明确要求在其他鼠标操作前移动到特定坐标时使用。
绝不能在未先使用
mouseMove
的情况下使用
mouseDown
或
mouseUp
— 这些操作在当前光标位置按下/释放按钮。在使用
```
mouseDown
```
/
```
mouseUp
```
之前，必须先使用
```
mouseMove
```
定位光标，否则位置不可预测。
绝不能自行添加断言 — 仅当AC明确说明预期结果时，才添加
```
expectText
```
/
```
expectVisible
```
/
```
expectNotVisible
```
（例外：导航时添加
```
expectUrl
```
，显示/隐藏操作时添加可见性断言对）。
绝不能在源元数据中存储绝对路径 — 约定为：git仓库使用仓库相对路径，外部文件仅使用文件名。
绝不能假设目标或值 — 若AC仅说"点击按钮"而未指明是哪个按钮，应向用户确认而非猜测。
```
button.generic
```
这样的通用目标会绕过受控词汇表系统，导致测试用例因匹配多个元素而不可预测地失败。
绝不能跳过验证 — 即使JSON看起来正确，在写入文件前也必须运行
```
npx validate-plan
```
，以捕获错误并减少清理错误产物的工作。
绝不能重用现有计划或测试用例 — 过去曾因此导致更改丢失，因此始终从AC源重新生成所有步骤以确保准确性。
绝不能在未验证的情况下写入计划文件 — 验证可捕获结构错误；写入无效计划会产生需要手动清理的损坏产物。
绝不能并行处理单个文件的多个步骤 — 完成单个文件的完整流程（AC → 计划 → 测试 → 摘要）后，再处理下一个文件，避免生成部分产物和状态混乱。
绝不能走捷径 — 当尝试自定义捷径时，智能体曾出现异常，因此触发后必须始终运行完整工作流。

Assessment mode output format

评估模式输出格式

When validation fails, report issues in this structure:

❌ AC are not conversion-ready. Issues found:

File: [filename]
1. [Line/Scenario reference]: [Specific issue]
   - Problem: [What's wrong]
   - Example: [Quote from AC]
   - Fix: [What needs to change]

File: [filename]
2. [Next issue...]

Example output:

❌ AC are not conversion-ready. Issues found:

File: form-actions.feature
1. Scenario "User submits form": Unknown action verb
   - Problem: "hovers" is not a recognized Playwright action
   - Example: "the user hovers over the tooltip"
   - Fix: Use a supported action (click, fill, select) or clarify the intent

File: login-flow.feature
2. Scenario "User logs in": Missing target intent
   - Problem: Test hook selector incomplete (button.form instead of button.form.submit)
   - Example: "clicks the button on the form"
   - Fix: Specify intent: "clicks the Submit button on the form"

When assessment passes:

✓ AC are conversion-ready

Validated ([X] AC in [Y] files):
- Structure: Proper format (bullets or Gherkin) with correct step ordering
- Targets: All meet the area/component/intent pattern with controlled vocabulary
- Actions: All verbs recognized (click/fill/select) with input values where required
- Expected outcomes: All explicitly stated and measurable
- Vocabulary: All areas/components match test-hooks.md keywords

These AC can be converted without modification.

Files analyzed:
[filename 1]
[filename 2]
...

当验证失败时，按以下结构报告问题：

❌ AC未准备好进行转换。发现以下问题：

文件: [文件名]
1. [行号/场景引用]: [具体问题]
   - 问题: [错误内容]
   - 示例: [AC中的引用内容]
   - 修复方案: [需要修改的内容]

文件: [文件名]
2. [下一个问题...]

示例输出：

❌ AC未准备好进行转换。发现以下问题：

文件: form-actions.feature
1. Scenario "用户提交表单": 未知操作动词
   - 问题: "hovers"不是可识别的Playwright操作
   - 示例: "用户悬停在提示框上"
   - 修复方案: 使用支持的操作（click、fill、select）或明确意图

文件: login-flow.feature
2. Scenario "用户登录": 缺少目标意图
   - 问题: 测试钩子选择器不完整（应为button.form.submit而非button.form）
   - 示例: "点击表单上的按钮"
   - 修复方案: 明确意图："点击表单上的提交按钮"

当评估通过时：

✓ AC已准备好进行转换

已验证（[X]个AC，来自[Y]个文件）：
- 结构：格式正确（项目符号或Gherkin），步骤顺序正确
- 目标：所有目标均符合area/component/intent模式并使用受控词汇表
- 操作：所有动词均可识别（click/fill/select），必要时包含输入值
- 预期结果：所有结果均明确陈述且可衡量
- 词汇表：所有area/component均匹配test-hooks.md中的关键词

这些AC无需修改即可转换。

已分析的文件：
[文件名1]
[文件名2]
...