用途:当测试需要锁定某个产出产物时使用,例如生成代码、序列化 JSON、命令输出、报告、迁移文件、渲染文档等,让审查者看到确切形状。核心问题是:预期契约变了,还是实现漂移。
主要能力:给出设计工作流,包括定义产物契约、将生成与比较隔离、比较前归一化易变内容、使用稳定差异比较、要求显式批准更新、验证更新纪律。提供归一化清单(排序映射与目录项、结构化文件规范格式、绝对路径替换为 <workspace>、时间戳与 UUID 等替换、随机种子、脱敏、保持归一化器窄)、稳定差异规则(小而命名的黄金文件、失败时保留实际输出、路径稳定命名、二进制用可审查替代物)、夹具归属规则与审批工作流。
使用方式:采用两步流程。只读检查为默认测试命令,生成实际输出、归一化、与已提交预期比较,失败时给出稳定差异与更新提示;显式更新由本地维护者运行如 UPDATE_GOLDENS=1 的选项命令或环境标志,确定性写入预期产物后审查 git 差异并重新运行只读测试。CI 只读,绝不更新黄金文件。
适用场景:产物是公开或集成行为、输出结构复杂以致单个断言会漏掉顺序格式省略或兼容性回归、审查者看差异比从小断言重建更快、产物属于审批工作流(如生成文档、模式、提示、报告、迁移、CLI 记录)。
限制:预期值小、行为纯数值或布尔、夹具主要编码偶然实现细节时应优先普通断言。缺失事实暂未提供,例如具体命令、依赖或价格。