端到端测试

<!-- @include templates/prompts/iron-law.md（已内联于下方，无需另读） -->

⛔ IRON LAW · 不可违反的硬门禁

以下规则为不可协商的执行约束：

1. 文件必须落盘：所有带编号（功能ID / 缺陷ID）的文档，必须作为实际文件写入磁盘，不可仅在对话中输出。
2. 阶段必须落章：每个阶段完成后必须在状态机 docs/.pdlc-state/<feature-id>.json 追加 history，不可跳过。
3. 测试必须存在：进入 /pdlc-implement 前，对应测试必须存在且处于红灯状态。违反则中止。
4. 自检必须执行：段二自检为强制步骤，不得以"已经很好了"为由跳过。
5. 防循环：段三修复为单次，不递归。无法自动修复的问题记录到报告，继续往下走。
6. 状态必推进：成功执行某 phase 后 current_stage 必须变更。收尾时若发现 current_stage 未推进，视为失败并报错，不得静默返回（防止外层循环拿滞后的状态空转烧额度）。唯一例外：命中人工点主动 block 时，current_stage 保持不变但必须写 last_phase_result.ok=false + blocked_reason。

违反任一条 = 立即中止当前命令，输出违规详情，等待人工介入。

<!-- @include-end templates/prompts/iron-law.md -->

编写端到端（E2E）测试用例，验证完整的用户操作流程。位置在实现之后、评审之前（下一跳 /pdlc-review，评审会把 E2E 结果一并纳入闸门）。

<!-- @include templates/prompts/artifact-lookup.md（已内联于下方，无需另读） -->

定位上游产物：先查状态机，再按关键词搜

守卫要找的上游文档（PRD、设计文档、评审记录等），按下面的顺序定位，命中即停：

1. 输入是功能ID / 缺陷ID（F… / B…）且 docs/.pdlc-state/<ID>.json 存在 → 读它 history[].produced 里记下的路径，取所需类型的文档。这是上游阶段亲手记的，最可靠
2. 没有状态机、或 produced 里没有所需文档 → 在对应目录下搜：文件名含该 ID 或功能名关键词，或文件顶部 PDLC 追溯头的 功能ID 等于该 ID
3. 命中多份 → 不要随手挑一份：交互模式下列出来请人选；--autonomous 下优先取文件名含该 ID 的，仍不止一份则按「真需人判断」阻塞（写 blocked_reason，列出候选）

找到后从文件名或追溯头取功能ID，后续产出一律沿用它，不另分配新 ID。

<!-- @include-end templates/prompts/artifact-lookup.md -->

PDLC 前置检查（必须执行，不可跳过）

1. 按上面的顺序找到本功能的 PRD（必需）与 UI 设计文档（docs/02_design/ui-ux/，有则读），确定功能ID
2. 检查实现是否已完成：状态机 current_stage 应为 impl（或更后）；没有状态机时，确认实现代码已存在
3. 未找到 PRD 或 实现未完成 → 输出以下信息后立即停止：

   ⛔ PDLC 守卫：「<功能名>」缺少 PRD 或实现尚未完成，E2E 测试无从验证。
   👉 /pdlc-prd <需求描述>  或  /pdlc-implement <功能ID>
   

工作流程

1. 阅读需求文档: 读 PRD 的用户故事与验收标准——E2E 用例从这里来
2. 阅读 UI 设计: 读 UI 设计文档（如有）
3. 梳理测试场景: 按用户旅程梳理核心操作路径（分级见下）
4. 编写测试计划: 在 docs/04_testing/e2e-tests/ 下创建 <功能ID>-<功能名>-e2e.md，文档顶部带 PDLC 追溯头
5. 编写测试代码（测试放哪）: 放进项目既有的 E2E 目录与框架（看 test-commands.yml 的 e2e 命令、playwright.config.* / cypress.config.* 的 testDir、已有的 *.spec.* / *.e2e.* 文件）；项目还没有 E2E 时，把选用的框架和目录写进报告
6. 对齐核心流映射: 若存在 docs/00_standards/e2e-flow-map.yml，本功能涉及的核心流（quality-targets.yml 的 core_flows）要把新写的测试标识填进对应 flow 的 tests——/pdlc-quality 靠这份映射机械判定「核心流都有 E2E」
7. 运行验证: 运行 bash scripts/pdlc-checks.sh --only e2e <项目根> 看结果；收尾的 scripts/pdlc-advance.sh 会再跑一次、把 {"e2e_pass":…} 写进 last_phase_result.checks，e2e_pass=false 时不推进。e2e 命令为空 → null（无法判定），在报告里提示补上 test-commands.yml 的 e2e

测试场景设计

• 核心路径（P0）: 必须通过，如登录→主流程→结果验证
• 分支路径（P1）: 常见的备选操作路径
• 异常路径（P2）: 网络错误、超时、权限不足等异常场景
• 边界场景（P3）: 空数据、超长输入、并发操作

测试框架（根据前端技术栈）

• React/Vue/Next.js: Playwright 或 Cypress
• 微信小程序: miniprogram-automator
• API 层: 直接用 HTTP 请求库

要求

<!-- @include templates/prompts/output-language.md（已内联于下方，无需另读） -->

🌐 Output language for generated artifacts

All generated artifacts (PRDs, design docs, code comments, review reports, test plans, deployment manuals, changelog entries, etc.) follow this policy:

1. Default — match the conversation language exactly:

   • 用户用中文与 Claude 对话 → 产中文文档、中文代码注释、中文报告
   • User talks to Claude in English → produce English artifacts
   • User talks in another language → produce artifacts in that language
   • Never silently default to a fixed language regardless of the user's input.

2. Explicit override always wins: when the user specifies a language for an artifact (e.g. "write the PRD in English", "用英文写 API 设计文档", "output the deploy doc in Japanese"), use that language for that artifact, regardless of conversation language.

3. Mixed-language requirements: if the user wants some artifacts in one language and others in a different language (common: Chinese PRD + English API docs for partners), honour each per-artifact instruction.

4. Uncertain: if you cannot reliably detect the conversation language, ask once before producing the first artifact.

This policy applies to content (prose, comments, headings). It does not override technical conventions like English variable names, English git commit subjects, or English error codes when the project's conventions require them.

<!-- @include-end templates/prompts/output-language.md -->

• 测试用例命名格式: 应该_当<条件>时_<预期行为>
• 测试数据独立，不依赖其他测试的执行结果
• 每个测试结束后清理数据

测试目标: $ARGUMENTS

<!-- @include templates/prompts/check-commands.md（已内联于下方，无需另读） -->

跑 check 命令：退出码的三态语义

用脚本跑，不要手写 checks：

bash scripts/pdlc-checks.sh --only <本阶段要的项，如 unit,lint> <项目根>

脚本是本 skill 自带的 scripts/pdlc-checks.sh。它读 docs/00_standards/test-commands.yml（唯一真源），逐条真跑，按下表映射，stdout 只有一行 JSON—— 原样写进 last_phase_result.checks，不改键名、不改值、不补不删。每条命令的退出码与输出末尾回显在 stderr，报告里引用那几行即可。脚本退出码 2（没有 yml 等）= 没有可跑的 check → checks: {}。

为什么不手写：键名、布尔类型、三态这几件事是确定性的，交给模型写，真机上同一份项目轮与轮之间就换一种错法 （键名照抄 yml 的 unit、值写成 "4 passed, 1 failed"、127 写成 false）。 环境里没有 bash 时才按下表手工映射。

脚本按退出码分三态——不是两态。这是 IRON LAW「checks 只认客观事实」在执行层的落法：

观察到的	含义	写进 checks
退出码 0	通过	对应键 = true
退出码非 0（命令跑起来了，只是没过）	未通过	对应键 = false
退出码 127 / command not found / 脚本文件不存在 / 该项为空字符串	无法判定	省略该键，或写 null——绝不能是 false

⛔ 唯一的红线是不许写 false：那是会误导人的虚报——它说的是"检查失败了"， 于是有人去查代码，但真正的问题是配置过期，代码可能完全没毛病。

省略键与 null 等价，两种都可以：对消费方而言无法区分（jq '.checks.lint_clean' 在两种情况下都返回 null）。null 甚至更明确——省略是歧义的（"没看"还是"看了判不出"）， null 明说"看了，判不出"。别在这上面纠结，力气花在不写 false 上。

这与「没有检查命令可跑的阶段 → checks: {}」同源。

「跑不了」＝ test-commands.yml 过期信号（顺带检测，零额外成本）

命令跑不起来，几乎总意味着这份 yml 已经跟不上项目了——脚本改名、runner 换了、 工具从依赖里移除、子项目路径调整。真实项目里这类漂移是常态（例如某前端框架升级后 移除了内置 lint 子命令，而 yml 里那条命令还在）。

由于各阶段本来就在跑这些命令，这个信号是白捡的。检测到时：

1. 在本阶段的报告里单列一条：「test-commands.yml 疑似过期」，写明是哪一项、 观察到什么（退出码 / 报错原文）、以及为什么判定为"跑不了"而非"没通过"。
2. 提示补救：/pdlc-test-setup --refresh（重新探测并给出 diff）。
3. 不要自作主张改 yml——本阶段的职责是干活，不是改配置；只报告，不动手。

变更方向决定自动化程度（--refresh 时适用）

更新这份 yml 等于改变"通过"的定义，所以按方向区别对待：

方向	例子	处理
让闸门变严	空着的 e2e 现在能跑了、覆盖率阈值上调	可自动应用，报告留痕
平移替换	命令改名但语义相同，且新命令已验证能跑	可自动应用，报告留痕
让闸门变松	删掉某条 check、把命令改成空、下调阈值	必须人确认，绝不自动

⚠️ 这条方向规则是防「自动修复把闸门修没了」：lint 命令坏掉时，把它留空是最省事的 "修法"，结果闸门悄悄松了、报告还是绿的——比不更新更危险。 变严可以自动，变松必须由人签字。

<!-- @include-end templates/prompts/check-commands.md --> <!-- pdlc:meta 由 frontmatter 生成（adapters/sync_skills.py），勿手改 -->

本命令的状态机取值：阶段短名 e2e（写进 history[].stage 与 last_phase_result.stage）；下一跳 pdlc-review（写进 next_step，交接时提示）。

<!-- pdlc:meta-end --> <!-- @include templates/prompts/state-update.md（已内联于下方，无需另读） -->

状态机更新（段四必须执行）

本命令完成主产出后，必须推进状态机文件 docs/.pdlc-state/<feature-id>.json。

用脚本推进，不要手写状态 JSON

bash scripts/pdlc-advance.sh <功能ID> --stage <本阶段短名> --next <下一跳命令名|null> \
  [--produced <产物路径，逗号分隔>] [--autonomous] [--decision "<确认点>=<所选默认>"]... \
  [--name <kebab-case>（状态文件还不存在时）] <项目根>

• 脚本是本 skill 自带的 scripts/pdlc-advance.sh。阶段短名与下一跳就是本命令正文里「本命令的状态机取值」那两个值；带了 --autonomous 就照传
• 检查由脚本自己跑：它按阶段调用同目录的 scripts/pdlc-checks.sh（tdd 验红灯；impl / fix / refactor 跑 unit、coverage、lint； review 再加 e2e；e2e 只跑 e2e；文档类阶段不跑），据此判 ok、整段写入 history 与 last_phase_result， 写完调用 scripts/pdlc-state-lint.sh 体检。不要自己先写 checks，也不要挑检查项
• tdd 阶段的 --produced 必须列出写的测试文件：脚本记下它们的指纹，之后 impl / refactor / review 推进时比对
• 主动交还人类（命中人工点、评审有阻塞项、测试本身有矛盾等）→ 加 --blocked "<原因>"：脚本照跑检查、如实记录，但不推进，原因写进 blocked_reason
• /pdlc-ship 写 ship_done、/pdlc-deploy 写 deploy_done → 加 --done（只有这两个命令能用）

脚本的退出码决定怎么收尾：

退出码	含义	你要做的
0	已推进	交接里引用 stdout 那行 JSON（checks、current_stage、next_step）
3	未推进：检查没过 / 红灯没验证 / 主动 block / tdd 写的测试被改	把 stdout 里的 blocked_reason 原样写进报告，按阻塞收尾。不要为了让它推进去改测试或改检查命令
2	脚本跑不了（参数错、缺 jq、状态文件损坏）	参数错就改正重跑；缺 jq 才按下面的格式手写，并在报告里写明「状态机未经脚本写入」

退出码 3 且原因是「tdd 阶段写的测试被改动」：实现阶段不改测试。测试是否真的写错了（与设计 / PRD 矛盾），只有人能判断：

• 交互模式：先把矛盾讲清楚、问人；人同意后再带 --tests-changed "<理由>" 重跑，理由记进 auto_decisions
• --autonomous：没有人可问，不要改测试，带 --blocked "<矛盾在哪>" 收尾。自主模式下带 --tests-changed 脚本也不推进

项目开了 PDLC 护栏（docs/00_standards/pdlc-hooks.yml）时，用 Write / Edit 直接写状态文件会被拦下。

状态文件格式（读状态时参考；只有脚本跑不了时才照它手写）

{
  "feature_id": "<F/B ID>",
  "feature_name": "<kebab-case>",
  "created_at": "<首次创建时间 ISO 8601>",
  "current_stage": "<当前阶段名>",
  "run_mode": "interactive | autonomous",
  "history": [
    {
      "stage": "<阶段名>",
      "done_at": "<ISO 8601>",
      "produced": ["<相对路径 1>", "<相对路径 2>"],
      "self_audit": { "passed": <N>, "failed": <N>, "manual": <N> },
      "auto_decisions": [
        { "point": "<autonomous 下自动前进的确认点>", "chose": "<所选默认>", "at": "<ISO 8601>" }
      ]
    }
  ],
  "last_phase_result": {
    "stage": "<本次阶段名>",
    "ok": true,
    "advanced_to": "<推进到的下一阶段 | null>",
    "checks": {},
    "self_audit": { "failed": 0 },
    "blocked_reason": null,
    "run_mode": "interactive | autonomous",
    "at": "<ISO 8601>"
  },
  "relations": {
    "extends": [],
    "depends_on": [],
    "supersedes": [],
    "resolves": [],
    "conflicts_with": [],
    "relates_to": [],
    "_updated_at": "<ISO 8601 | 省略>"
  },
  "next_step": "<下一跳命令名，如 pdlc-design；若流程结束则为 null>"
}

⛔ 示例里的 "checks": {} 是「本阶段没有命令可跑」的样子，不是键名示范——键名与取值见下方 §1。

relations 块（RFC#6，Phase 1 可选，Phase 2 推荐）：6 个 key 对应 6 种关系类型，各为 ID 数组，存出边。其中 conflicts_with / relates_to 是对称类型，两端都要写；其余四种有向，只写在源 feature 上。拿不准时用 /pdlc-relate set 写入，它会按规则校验。旧状态文件无此块时视为全空，向后兼容。入边由 /pdlc-relate rebuild 派生到 _relations.json，不在此块手维护。

⛔ 写状态机的四条硬约束——读侧（/pdlc-status、/pdlc-retro、/pdlc-relate）会逐条体检， 违反的每一处都会出现在它们输出的最前面：

1. 实例里不写 terminal_state。skill frontmatter 的 terminal_state: 是「这个命令走完后应到达的终态名」， 不是状态字段。判终态只看 current_stage 是否以 _done 结尾。
2. history[].stage 写本命令的阶段短名（见本命令正文里「本命令的状态机取值」）——pdlc-implement 写 impl， 不写 implement / implementation；pdlc-prd 写 requirements，不写 prd。
3. 时间戳必须带时刻：created_at / done_at / at 一律写完整 ISO 8601（如 2026-07-28T10:40:00+08:00）。 只写日期，同一天内的阶段耗时就全部算成 0——读侧只能记「不可测」。
4. next_step 只写命令名或 null，不附说明文字（如「pdlc-ship（等评审通过）」）。 要说明原因，阻塞时写进 last_phase_result.blocked_reason。

⛔ _done 的含义是「已发布」，只由 /pdlc-ship（写 ship_done）与 /pdlc-deploy（写 deploy_done）写入。 其它命令的 current_stage 一律写本命令的阶段短名，走完整条链路的编排命令（/pdlc-feature）也一样—— 它收尾时 current_stage 是最后一个阶段的短名，next_step 是 pdlc-ship。

• 「评审通过、等待发布」就是 current_stage 为 review 且 next_step 为 pdlc-ship（/pdlc-e2e 在评审之前，它的下一跳是 pdlc-review）。 循环相关文档里说的 review_done 指的就是这个状态，不是要写进 current_stage 的值。
• 为什么：读侧判「已抵达终态」只看 current_stage 是否以 _done 结尾。评审通过就写 _done， /pdlc-ship 就分不清哪些功能已经发布过，发布说明会重复或漏收。
• 旧版本写入的 feature_done / fix_done / review_done 分不清是否已发布，/pdlc-ship 会列出来请人确认。

手写回退（仅脚本退出码 2 且无法修正时）

1. 文件不存在 → 创建文件，写入初始结构（history 为含当前阶段的数组）
2. 文件存在 → 读取 JSON，追加当前阶段到 history，更新 current_stage 和 next_step
3. 写回文件：用 jq 或等效工具保持格式化
4. 写完体检：运行 bash scripts/pdlc-state-lint.sh <项目根>，属于本功能状态文件的偏差当场改正。退出码 2（缺 jq 等）= 没体检，报告里写明「未体检」，不得当作通过。

⚠️ 若更新失败（文件损坏/权限问题），必须中止命令并在最终报告中报错。状态机不可跳过。

last_phase_result（机器可读阶段结果；脚本按下面的规则写，手写回退时照做）

顶层 last_phase_result 是循环判停的唯一真源，外层只需 jq '.last_phase_result.ok' 即可决定 继续 / 停止 / 交还人类。规则：

1. checks 只放真跑命令的退出码结果（scripts/pdlc-checks.sh 的 stdout 原样），键名只能是 tests_pass / coverage_pass / lint_clean / e2e_pass（tdd 段 red_verified），值只能是布尔或 null（无法判定）。不照抄 test-commands.yml 的 unit / lint， 不写 "4 passed, 1 failed" 这类摘要。没有检查可跑的阶段（文档类阶段、项目无 test-commands.yml）→ checks: {}， 绝不因为「本阶段成功」就填 true——schema 示例里 checks 是空的，正是这个意思。

2. self_audit 单列：只放自检未通过数，仅供参考，不作循环判停依据。

3. ok 的定义：没有命中 blocked_reason，且 tdd 段 red_verified 为 true、其它阶段没有任何检查为 false（null 不拦）→ true；否则 false。

4. 命名空间：advanced_to = 下一阶段的短名，不是命令名、也不是本阶段的 current_stage。三者关系：stage=本阶段短名、current_stage=本阶段完成后的当前短名、advanced_to=下一阶段短名、next_step=下一跳命令名。

   ⛔ 短名不是「命令名去掉 pdlc- 前缀」——pdlc-implement 的短名是 impl，不是 implement。别推导，查下表：

<!-- stage-map:start -->

next_step（下一跳命令名）	advanced_to（下一阶段短名）
pdlc-tdd	tdd
pdlc-implement	impl
pdlc-review	review
pdlc-design	design
pdlc-ship	ship
pdlc-deploy	deploy

<!-- stage-map:end -->

next_step 为 null（终态或无后续）时 advanced_to 也是 null。

📌 本表是唯一真源，且是被断言钉住的：每行的短名必须等于该 skill 自己 frontmatter 里声明的 stage:，且任何 skill 的非 null next_step 都必须在表里有行——两个方向 都由 tests/frontmatter-check.sh 检查，所以表不会和实现各自漂移。

写错短名的后果与键名写错同类：消费方按契约名匹配，认不出就当没这个阶段。 5. 推进一致：ok=true 时本阶段必须真的推进了 current_stage（与第 6 条 IRON LAW 呼应）；到达终态或无后续时 advanced_to=null。ok=false（含 blocked）时 current_stage 不变、advanced_to=null、blocked_reason 写明原因。 6. run_mode：镜像本次调用是否带 --autonomous（带了写 autonomous，没带写 interactive）。

<!-- @include-end templates/prompts/state-update.md --> <!-- @include templates/prompts/handoff.md（已内联于下方，无需另读） -->

段四：交接（Handoff）

命令完成后必须输出以下格式的最终消息：

✅ <阶段名> 完成：<主要产出物路径>
📊 自检：<通过数>/<总数> 通过（若有未通过，附要点）
📦 状态快照：docs/.pdlc-state/<feature-id>.json
👉 下一步：/pdlc-<next_step>
   （如果有分叉）或 /pdlc-<alt>（条件：<选择依据>）

规则：

• 主流程命令（写状态机的命令；下一跳见正文里「本命令的状态机取值」）必须显式输出"下一步"，不可省略
• 工具型命令（Layer 3）可以没有 next_step，此时输出 👉 下一步：（本次流程结束，无后续）
• 分叉场景必须说明选择条件，例如"若需补充测试用例 → /pdlc-tdd；若测试已齐 → /pdlc-review"<!-- @include-end templates/prompts/handoff.md -->