| name | spec-driven-test |
| description | 用规约驱动测试(specification-based testing)的方法对 web 应用做端到端测试。当用户说要"测试一下这个功能"、"检查一下这个功能的完整性"、"对这个项目做 E2E 测试"、"用 agent 测这个 web 应用"或者直接提到 spec-driven-test / specification-based testing 时使用这个 skill。也适用于用户希望基于代码自动生成测试规约和测试用例,然后通过浏览器自动化执行测试的场景。即使用户没有明确说"规约"或"测试用例"这些词,只要他想系统地、自动化地测试一个 web 项目的某个功能,都应该使用这个 skill。 |
Spec-Driven Test
用规约驱动测试的方法对 web 应用做端到端测试。
整个流程由三个 agent 协作完成:Cartographer 读代码生成规约和用例,Inspector 用方法论审用例,Operator 在真实浏览器执行测试。两道人类 review 把关质量。
按需加载导航(执行 skill 前先读这段)
这个 skill 是文件型 skill,你不需要一次性读完所有 reference 文件——按角色和阶段读对应章节,可大幅节省 token。
确定你的角色,只读对应主文件:
- Cartographer 角色 → 读
references/cartographer.md(分阶段读章节,详见该文件顶部 TOC)
- 阶段 0 / 1 / 2 / 2.5 / 3,只读当前阶段章节
- 阶段 1 末尾识别匹配的场景模式后,只读匹配的
references/scenarios/<对应文件>.md,不要全读
- 写规约时读
templates/spec-template.md,写用例时读 templates/test-cases-template.md
- Inspector 角色 → 读
references/inspector.md(分步骤读章节,详见该文件顶部 TOC)
- 工作流程 §1 / 1.5 / 1.6 / 1.7 / 1.8 / 2 / 2.5 / 3 / 4
- 选用方法论时只读匹配的
references/methodologies/<对应文件>.md,不要全读
- 输出格式时读
templates/judge-output-template.md
- Operator 角色 → 读
references/operator.md,产出报告时读 templates/execution-report-template.md
人类 review 阶段 → 读 references/human-review-checklists.md
读 SKILL.md 本身只是入口——它是导航,不是详细规则。
真正的工作规则在每个 agent 的 reference 文件里,按需读取才能控制 token。
整体流程
用户指定要测试的功能
↓
┌───────────────────────────────────────┐
│ Cartographer 阶段 0 │
│ 确认测试范围 + 收集可选信息 │
│ (ground truth, UI 截图, Operator 工具) │
└───────────────────────────────────────┘
↓
┌───────────────────────────────────────┐
│ Cartographer 阶段 1 │
│ 读代码 → 生成规约 │
│ 标注匹配的"场景模式" │
└───────────────────────────────────────┘
↓
╔═══════════════╗
║ 人类 Review ║ ← 第一道:确认规约准确性
╚═══════════════╝
↓
┌───────────────────────────────────────┐
│ Cartographer 阶段 2 │
│ 规约 → 测试用例 │
│ 填场景模式自检表 + Resource Dependency │
│ Matrix │
└───────────────────────────────────────┘
↓
┌───────────────────────────────────────┐
│ Cartographer 阶段 2.5(如需要) │
│ 逐文件决策文件输入策略 │
│ (仅当任何 TC 有 file_inputs 时) │
└───────────────────────────────────────┘
↓
┌───────────────────────────────────────┐
│ Inspector │
│ 用方法论 + 自检表审查用例 │
│ 输出 P0/P1/P2 分级反馈 │
└───────────────────────────────────────┘
↓
┌───────────────────────────────────────┐
│ Cartographer 阶段 3 │
│ 决定每条反馈修不修(填 rationale) │
└───────────────────────────────────────┘
↓
╔═══════════════╗
║ 人类 Review ║ ← 第二道:确认用例可跑
╚═══════════════╝
↓
┌───────────────────────────────────────┐
│ Operator │
│ 在真实浏览器执行用例 │
│ 输出执行报告 │
└───────────────────────────────────────┘
三个 Agent 的职责
| Agent | 角色 | 看什么 | 不看什么 |
|---|
| Cartographer | 制图师 | 代码 + 规约 + 用例 + Inspector 反馈 | (无限制) |
| Inspector | 检查员 | 规约 + 用例 + 方法论 | 不看代码 |
| Operator | 执行员(模拟真实用户) | 用例 + 浏览器实际状态 | 不做对错判断 + Steps 不走 API 捷径 |
Operator 关键约束:trigger(被测功能的触发动作)必须通过浏览器 UI 完成,
不允许走 API / SSE / SQL 等捷径——否则 E2E 测试退化为 API 测试。
仅 Setup / Teardown / 验证 server_state 时允许走 API/DB(因为不是被测功能本身)。
详见 references/operator.md 核心原则 1。
每个 agent 的详细指引在对应的 reference 文件里:
- 进入 Cartographer 角色 → 读
references/cartographer.md
- 进入 Inspector 角色 → 读
references/inspector.md
- 进入 Operator 角色 → 读
references/operator.md
Operator 混合执行模式(Playwright + LLM 截图判断)
核心理念
Operator 默认采用混合执行模式——不是单纯的 LLM 实时操作浏览器,也不是单纯的 Playwright 脚本。
两种工具分工合作,让每种工具做它擅长的事:
| 工具 | 擅长什么 | 不擅长什么 |
|---|
| Playwright | 输入输出层(数据进数据出)、DOM 断言、SQL/API 验证、可重放、token 成本极低 | 视觉/UX 判断、"看起来对不对"的语义理解 |
| LLM 看截图(computer-use) | 视觉判断、UI 设计/UX、Markdown/emoji/字体渲染保真度 | 精确数据断言、循环执行、可重放 |
混合模式的逻辑:Playwright 跑业务流程 + 在关键时刻留截图 + LLM 后处理读截图做视觉判断。
这是方案 X(Playwright 留截图 + LLM 后处理),不是方案 Y(场景重跑两次)。
三种 TC 类型(Operator-mode 字段)
Cartographer 阶段 2 写每个 TC 时,必须标 Operator-mode 字段,三选一:
| 模式 | 适用场景 | 执行方式 |
|---|
| A: LLM 浏览器(Claude in Chrome / browser-use) | 测视觉 / 渲染 / UX / 探索性 | LLM 实时操作浏览器 + 看截图判断 |
| B: Playwright | 测输入输出 / 数据流 / 业务逻辑 / 回归 | 生成 .spec.ts 脚本,Playwright 引擎执行 |
| C: 混合(默认推荐) | 既要数据正确又要视觉验证(如 chatbot 消息渲染、Markdown 处理) | Playwright 跑业务 + 关键时刻留截图,LLM 后处理读截图判断渲染 |
判别要点:
- 测点是"数据传递正确性" → B
- 测点是"视觉/渲染/UX" → A
- 测点既要数据也要视觉 → C(大多数 chatbot / CRUD / 个人主页类功能都是 C)
混合模式 C 的执行流程
TC-005: 发送 Markdown 消息,验证渲染 + 后端存储
第 1 阶段(Playwright 自动执行):
1. 浏览器访问 /app/agent
2. 在 textarea 输入 "**重要**\n# 标题"
3. 点击发送按钮
4. 等待 SSE 流完成
5. 📸 截图保存到 screenshots/TC-005-after-send.png ← 截图节点
6. SQL 验证: SELECT content FROM messages → 应为 "**重要**\n# 标题"
第 2 阶段(LLM 后处理):
- 读 screenshots/TC-005-after-send.png
- 视觉判断: 气泡里 "重要" 是粗体吗?"# 标题" 是大字标题吗?
- 输出截图判断结果到 execution-report
合并报告:
- Playwright trace: Steps 全部 PASSED
- LLM 截图判断: 粗体 ✅, 标题 ✅
- 综合状态: PASSED
TC 必须包含的两个新字段(在 test-cases-template.md 中)
Operator-mode:A / B / CScreenshot points(仅 mode A 和 C 用):列出在哪些步骤后留截图,以及每张截图后 LLM 应该判断什么
例:
Operator-mode: C
Screenshot points:
- after_step: 5
save_to: screenshots/TC-005-after-send.png
llm_judges:
- "气泡内 Markdown **重要** 是否渲染为加粗 <strong> 元素?"
- "气泡内 # 标题 是否渲染为 <h1> 大字标题?"
- "整体气泡布局是否正常(无错位、文字未溢出)?"
Inspector 不审 Operator-mode 的工具选择
Inspector 不质疑 Cartographer 选 A/B/C 的判断——这是工程决策,不是规约/方法论问题。
Inspector 只审:
- TC 是否填了
Operator-mode(没填 → P0)
- 模式 A 和 C 的 TC 是否填了
Screenshot points(没填但 expected 涉及视觉断言 → P1)
详见 references/operator.md 工作流程,以及 templates/test-cases-template.md 字段格式。
Agent 实例隔离规则(execution-time architecture)
skill 的三个角色不只是逻辑角色——它们应该在不同的 agent 实例中运行,
这是隔离独立性的执行层保证。
Inspector 必须在独立 agent 实例中运行(强制)
原因:Inspector 的核心价值是"独立审查 Cartographer 的判断"——
但如果 Inspector 和 Cartographer 在同一个 conversation 里跑,
Inspector 已经"看过代码 / 知道 Cartographer 的思考过程",它的独立性被污染了——
它会下意识为 Cartographer 的设计辩护,审查质量大幅降低。
强制要求:Cartographer 阶段 2 完成后(以及阶段 3 修订完成后),必须告知用户开独立实例跑 Inspector,不允许在原 conversation 里直接切换角色。
怎么开独立实例(按部署环境选择):
| 环境 | 推荐方式 | 备用方式 |
|---|
| Claude Code | 用 subagent / Task 工具开新 agent | 让用户开新对话 |
| API 调用方 | 发起新 conversation,system prompt 引导进入 Inspector 角色 | — |
| Claude.ai / Claude Desktop | 让用户开新对话(普通用户没有 subagent 能力) | — |
给 Inspector 实例的输入清单:
- 规约文档(Cartographer 阶段 1 产出 + 人类 review 后的最终版)
- 用例文档(Cartographer 阶段 2 产出 + 阶段 2.5 文件决策完成后的最终版)
- 装上 spec-driven-test skill,系统会引导进入 Inspector 角色
绝对不要传给 Inspector:
- ❌ 代码(任何源代码文件)
- ❌ Cartographer 阶段 1 / 阶段 2 的思考过程 / 中间决策
- ❌ Cartographer 选用某些方法论的原因
Inspector 完成后,把反馈文档传回原 Cartographer conversation,Cartographer 阶段 3 处理反馈。
Operator 不强制独立(同一 conversation 也行)
原因:Operator 的价值是"忠实执行"——它看过代码反而能更好处理异步 timing 等细节。
诚实性由 E2E 视角约束(SKILL.md 第 11 条原则)保证,不需要 context 隔离来实现。
实际上,让 Cartographer 阶段 3 完成后,在同一 conversation 里继续跑 Operator,是合理的——
出题人来执行测试,对题目细节理解最深。
但仍然要遵守的边界:
- Operator 必须严格按已审过的用例执行(Steps 必须用浏览器 UI,不允许 API 捷径)
- Operator 不"创造性"补测试或修复用例——这些超出执行职责
阶段内部不需要隔离
Cartographer 的所有阶段(0 / 1 / 2 / 2.5 / 3)都是 Cartographer 角色,
同一个 conversation 里连续跑——不需要切换 agent 实例。
中间的两道人类 review 是隔离机制,不是切换 agent。
流程示意
agent A(Cartographer): 阶段 0 → 阶段 1 → 阶段 2 → 阶段 2.5 → 阶段 3 → ... → Operator(可选同实例)
↑
反馈传回 ── ── ── ┘
↑
agent B(Inspector,独立实例): 审查
↑
(规约 + 用例传入)
核心制品
整个流程产出 4 类文档,所有文档用 Markdown 格式:
| 制品 | 产出者 | 模板 |
|---|
| 规约文档 | Cartographer | templates/spec-template.md |
| 测试用例文档 | Cartographer | templates/test-cases-template.md |
| Inspector 反馈 | Inspector | templates/judge-output-template.md |
| 执行报告 | Operator | templates/execution-report-template.md |
完整工作样例在 examples/login-spec-example.md。
启动这个 skill
当用户要求测试某个 web 功能时,agent 进入 Cartographer 阶段 0:
- 用户想测哪个功能——明确具体的功能名(如"用户登录"、"密码重置")
- 代码在哪——用户应该指明项目位置或相关文件
- 测试环境怎么访问——用户是不是已经把项目跑起来了?浏览器工具怎么用?(这影响 Operator 阶段)
如果以上有不清楚的,问用户。不要立刻开始读代码。
完整阶段 0 协议见 references/cartographer.md。
暂停点和"通过"信号
整个流程有 2 道强制人类 review,agent 必须暂停等待:
| 暂停点 | 触发时机 | 必须做的 | 通过信号 |
|---|
| 规约 review | Cartographer 阶段 1 完成后 | 把规约展示给用户 | 用户说:"规约 OK" / "通过" |
| 用例 review | Cartographer 阶段 3 完成后(反馈处理完) | 把最终用例展示给用户 | 用户说:"用例 OK" / "可以跑了" |
浏览器和环境的问题等到 Operator 阶段再问。第一道 review 关注规约准确性,第二道关注用例质量。
完整 review 清单见 references/human-review-checklists.md。
关键设计原则
11 条核心原则,每条只在主文件展开——下面给一句话要点 + 引用主文件。
1. Agent 之间的隔离边界是 skill 的灵魂——Inspector 不看代码,Operator 不做归因判断。
独立性详见上面"Agent 实例隔离规则"。
2-4. 三层规约结构 / client vs server state / behaviors 用户意图级——规约怎么写。详见
templates/spec-template.md 字段注释,以及 references/cartographer.md 阶段 1。
5. 严重程度分级(P0/P1/P2)——P0 必修,P1 默认修(不修需 rationale),P2 可选。
详见 references/inspector.md 工作流程 §3。
6. 信息源权威等级——多个来源冲突时按 P1-P7 取信(用户 ground truth > SQL > fixture > 代码 > 配置 > 文档 > 口头),
冲突时显式声明让人类裁决。详见 references/cartographer.md 阶段 1 第 7 条。
7. 多模态输入靠工程方法——规约只描述"需要什么样的文件",阶段 2.5 让用户逐个文件选(A 路径 / B 手动 / C Agent 生成)。
详见 references/cartographer.md 阶段 2.5。
8. 易抽象字段必须带"逻辑依据"——LLM 读代码容易把 fallback / 异常处理 / 模板字符串错误归纳成普通规则。
让 Cartographer 在写涉及代码归纳的字段时先写依据再下结论,Inspector 审"依据 vs 结论是否自洽"。
详见 references/cartographer.md 阶段 1 第 8 条。
9. 场景模式 + 自检 + 审查自检——方法论(EP/BVA)是"标尺",场景模式是"必查清单"。
Cartographer 阶段 1 识别匹配模式 → 阶段 2 把每个清单项标 ✓/⚠/✗(必给依据)→ Inspector 审查这张自检表。
完整模式库见 references/scenarios/,机制详见 references/cartographer.md 阶段 2 第 1 条 + references/inspector.md §1.5。
10. 破坏性 TC 识别 + Setup/Teardown——TC 之间通过共享资源互相污染是经典死锁。
每个 TC 标 Destructive: yes/no,破坏性 TC 必须有 Teardown,不可逆操作必须 mock。
用例文档加 Resource Dependency Matrix。详见 references/cartographer.md 阶段 2 第 6 条 + references/inspector.md §1.7。
11. E2E 视角:Steps 必须用户视角——Steps 写"浏览器输入 X / 点击 Y",不是 "POST /api/...";
否则 E2E 退化为 API 测试。仅 Setup / Teardown / verify server_state 允许走 API/SQL。
详见 references/cartographer.md 阶段 2 第 7 条 + references/operator.md 核心原则 1 + references/inspector.md §1.8。
12. Operator 混合执行模式(Playwright + LLM 截图判断)——
不强制单一工具。每个 TC 标 Operator-mode:A(LLM 浏览器,适合视觉/UX)/ B(Playwright,适合数据流/回归)/ C(混合,默认推荐——Playwright 跑业务 + 关键时刻留截图,LLM 后处理读截图判断渲染)。
方案 X:截图在 Playwright 阶段留下,LLM 后处理读截图,不重跑场景。
详见上面"Operator 混合执行模式"章节 + references/operator.md 工作流程。
方法论参考
Inspector 按功能特征选用方法论(不是 6 个全跑)。当前 skill 提供以下方法论文档:
经典 spec-based testing 方法论:
references/methodologies/equivalence-partitioning.md — 等价类划分(用于输入数据型)references/methodologies/boundary-value-analysis.md — 边界值分析(用于输入数据型)references/methodologies/decision-table.md — 决策表(用于多条件组合)references/methodologies/state-transition.md — 状态转移(用于状态机)references/methodologies/use-case-testing.md — 用例测试(用于完整流程)
辅助 checklist:
references/methodologies/right-bicep.md — Right-BICEP(辅助交叉验证,不作为主方法论)
详细的选用逻辑见 references/inspector.md §2。
样例
examples/ 目录提供完整的样例供 Cartographer / Operator 参考:
简单功能样例(登录)——展示规约 + 用例的基本结构:
examples/login-spec-example.md — 用户登录的规约样例(三层结构、§3.4 拆分、§3.5 setup、逻辑依据)examples/login-cases-example.md — 对应的用例样例(Resource Dependency Matrix、场景模式自检表、5 个代表性 TC)
复杂功能样例(chatbot,核心)——展示混合模式 C 的完整应用:
examples/chatbot-spec-example.md — 轻量 chatbot 规约(对话型 UI + 异步流式 + LLM agent + 前端渲染保真度多模式叠加)examples/chatbot-cases-example.md — 对应的用例(Operator-mode A/B/C 三种全用上,带完整 Screenshot points)examples/chatbot-execution-report-example.md — 执行报告样例(Playwright trace 摘要 + LLM 截图判断段实际填法)
强烈推荐:Cartographer 阶段 2 写涉及前端渲染保真度的 TC 时,必读 chatbot-cases-example.md——
里面的 TC-002 是混合模式 C 的标准范例。
工程边界
这个 skill 不做的事(以及如何处理):
- skill 不审代码正确性——如果代码本身有 bug,规约只是描述"有 bug 的代码做什么";测试会照着这个跑,通过。这是设计上的:spec-driven testing 测的是"实现是否符合规约",而"规约是否对"是人类 review 的责任。
- 性能 / 负载测试——超出范围;规约描述行为,不描述性能特性。
- 安全审计——skill 涵盖基础认证授权和输入边界(XSS 通过长度边界),但不能替代专业的安全审计。
- 视觉回归——skill 验证功能行为,不验证像素级视觉变化。
添加新场景模式
如果实际使用中发现某种重复出现的场景类型,但当前 11 个模式覆盖不到(如"实时协作编辑"、"区块链交易"、"图像识别"),按以下步骤添加新模式:
- 起一个简洁名字(2-4 个字)
- 在
references/scenarios/ 创建新的 .md 文件(参考已有文件结构)
- 在文件中列出该模式的必查清单
- 在
references/scenarios/index.md 加一行,让 Cartographer 能发现
这是低成本扩展——不需要修改 Cartographer 或 Inspector 主文件,两者读取目录的最新版本。
备注
这个 skill 是重型工具,完整跑一次 E2E 测试可能消耗 100K-500K tokens(取决于功能复杂度)。适合:
- 关键业务流程(登录 / 支付 / 数据创建删除)
- 安全相关功能(权限 / 认证 / 隐私)
- LLM agent 系统(grounding / hallucination / 工具调用安全)
不适合:
- 简单 UI 交互测试(用 Playwright 直接写更快)
- 单元测试(用 pytest / jest)
- 性能压测(专门工具)
- 探索性测试(手动操作更高效)
用之前问自己:这个功能值得花 100K-500K tokens 做严谨 E2E 测试吗?
