acceptance-pipeline-catalog

Robert C. Martin 验收流水线最佳实践

与语言无关的可移植验收测试流水线规范：从 Gherkin 功能文件到 JSON IR，再到生成的验收测试和变异测试。基于 Robert C. Martin 的《验收流水线规范》。包含约 50 条规则，分为 14 个类别，并按影响程度排序。

适用场景

在以下情况下参考这些规则：

• 构建输出 JSON IR 的 Gherkin 解析器
• 实现根据 JSON IR 生成验收测试的生成器
• 编写用于展开场景并分派步骤的验收运行时
• 为验收测试的示例值实现变异测试
• 在新项目中搭建完整流水线（解析器、生成器、运行器、变异器）
• 调试流水线故障（解析错误、生成问题、变异分类）

流水线概览

流水线有两种模式：

正常验收运行：

feature file -> gherkin parser -> JSON IR -> acceptance generator -> generated tests -> test runner

变异运行：

feature file -> gherkin parser -> base JSON IR -> mutator (one changed IR per mutation)
  -> generator (tests per mutation) -> test runner (evaluate each) -> mutation report

正常运行证明项目满足该功能的要求。变异运行则用于探测测试是否足够健壮，能在示例数据发生变化时失败。

按优先级划分的规则类别

优先级	类别	影响	前缀	规则数
1	解析器	严重	parser-	9
2	JSON IR	严重	ir-	4
3	生成器	严重	gen-	2
4	运行时	高	rt-	3
5	步骤处理器	高	handler-	4
6	测试运行器	高	runner-	2
7	变异核心	高	mut-	4
8	值变异规则	高	val-	10
9	结果分类	高	result-	2
10	一致性	高	conform-	1
11	Agent 设置	高	setup-	1
12	变异执行	中	exec-	4
13	报告	中	report-	3
14	项目布局	中	layout-	3

快速参考

1. 解析器（严重）

• parser-command-interface - 两个位置参数，退出代码为 0/1/2
• parser-feature-declaration - 必须使用 Feature: 关键字，名称需去除首尾空格
• parser-background - 可选的 Background: 部分，包含 Given/And 步骤
• parser-scenarios - 同时支持 Scenario: 和 Scenario Outline:
• parser-steps - Given/When/Then/And 关键字，关键字单独存储
• parser-parameters - 尖括号占位符，解析器不展开
• parser-examples-tables - 竖线分隔的表格，首行为标题行
• parser-general-rules - 空行、注释、空白字符、顺序
• parser-unsupported-syntax - 标签、规则、本地化关键字、文档字符串

2. JSON IR（严重）

• ir-feature-object - name、scenarios、可选的 background
• ir-scenario-object - name、steps、examples 数组
• ir-step-object - keyword、text、可选的 parameters
• ir-example-object - 键和值均为字符串的映射

3. 生成器（严重）

• gen-command-interface - 两个位置参数，退出代码为 0/1/2
• gen-requirements - 嵌入 IR，不解析 Gherkin，输出具有确定性

4. 运行时（高）

• rt-responsibilities - 加载 IR、展开、分派、报告
• rt-scenario-expansion - 每个示例行执行一次，并将背景步骤前置
• rt-execution-naming - 场景名称 / 示例索引命名约定

5. 步骤处理器（高）

• handler-matching - 按完全匹配的文本值匹配，而非关键词
• handler-world-state - 每次场景执行都创建全新的世界状态
• handler-value-handling - 获取、解析；缺失或格式错误时失败
• handler-unsupported - 不支持的步骤文本必须导致测试失败

6. 测试运行器（高）

• runner-interface - 测试运行器适配器的输入/输出约定
• runner-classification - 三种分类：失败、成功、基础设施错误

7. 变异器核心（高）

• mut-command-interface - 命令行选项、退出代码 0/1/2
• mut-scope - 仅变异示例单元格值
• mut-identity - 稳定且确定的 ID、路径和描述
• mut-deep-copy - 永不原地修改原始 IR

8. 值变异规则（高）

• val-rule-order - 按优先级应用 8 条规则
• val-comma-list - 逗号分隔列表的变异
• val-boolean - true/false 切换
• val-null - 将 null/nil/none 转换为抖动字符串
• val-integer - 整数加上伪随机增量
• val-float - 浮点数加上伪随机增量
• val-datetime - ISO-8601 日期/时间偏移
• val-duration - 偏移持续时间并保留语法
• val-string-dither - 逐字符编辑字符串
• val-determinism - 伪随机；固定输入下结果确定

9. 结果分类（高）

• result-statuses - killed、survived、error
• result-classification-rules - 将测试结果映射为状态

10. 一致性（高）

• conform-checklist - 全部 21 项验证内容

11. Agent 设置（高）

• setup-checklist - 15 步安装指南

12. 变异执行（中）

• exec-work-directory - 每个变异对应的目录结构
• exec-workflow - 写入 IR、生成、运行、分类
• exec-parallelism - 并发工作器、隔离目录
• exec-timeout - 全程运行超时；未完成则标记为错误

13. 报告（中）

• report-text-format - 摘要行和逐结果行
• report-json-format - 包含摘要和结果数组的 JSON 对象
• report-field-requirements - 摘要和结果的必需字段

14. 项目布局（中）

• layout-required-paths - features/、build/、acceptance/ 目录
• layout-commands - gherkin-parser、acceptance-generator、gherkin-mutator
• layout-scripts - 常规验收脚本和变异脚本

使用方法

阅读各个参考文件，了解详细的规范要求和设计依据：

• 从与你要构建的组件相关的类别开始
• 每个规则文件都独立完整，包含 WHY 说明、规范要求和示例
• 设置新项目时，先阅读 setup-checklist
• 进行验证时，使用 conform-checklist
• 查看 gotchas.md，了解已知的易错点

参考文件

文件	描述
metadata.json	版本和参考信息
gotchas.md	已知问题点（仅追加）
references/	按前缀整理的所有规则文件