testing-codegen

测试与代码生成

选择能够覆盖变更行为的最小范围测试；只有在共享基础设施或集成风险确有需要时，才扩大测试范围。

测试选择

变更	从以下测试开始
Lint 规则	just test-lintrule <ruleName>
一个 crate	cargo test -p <crate> 或该 crate 的定向测试目标
调查解析器或格式化程序	just qt <package>
CLI 迁移	定向 biome_cli 迁移测试
文档代码	just test-doc

仅在需要测试诊断输出时，才使用 -- --show-output 或 --nocapture。

快速测试是用于检查 CST、格式化程序 IR 或某个分析器查询的临时空间。持久化行为应在结束前放入子系统常规的 fixture 目录。

Snapshot 工作流

运行定向测试以创建待处理的 snapshot。单独处理无关的测试失败。绝不要手动更新、添加或删除 snapshot。让 insta 来处理。

Agent 不得运行未过滤的 cargo insta review；它需要 TTY。在非 TTY 的 Agent shell 中，cargo-insta 1.44+ 会打印经过过滤的 --snapshot 差异，而不会提示：

cargo insta pending-snapshots --workspace
cargo insta review --workspace --snapshot '<path-from-list>'

检查完整差异后，只接受或拒绝该 snapshot：

cargo insta accept --workspace --snapshot '<same-path>'
cargo insta reject --workspace --snapshot '<same-path>'

对每项变更重复此过程，再次列出待处理的 snapshot，然后重新运行测试。审查意味着检查差异中的行为。测试通过只能证明输出与 snapshot 相符。

绝不要使用未过滤的 cargo insta accept 或 cargo insta reject、cargo insta test --accept、cargo insta test --force-update-snapshots 或 INSTA_UPDATE=always/force。它们会跳过逐项审查，并可能修改无关的工作内容。

孤立的 Snapshot

不要手动删除疑似孤立的 snapshot。只有在不使用 package、target 或 test 过滤条件运行完整的 workspace snapshot 测试套件后，才能安全删除：

cargo insta test --workspace --unreferenced delete

对于范围受限的运行，请使用 --unreferenced warn 或 --unreferenced reject；不完整的测试选择无法证明某个 snapshot 已孤立。检查完整运行产生的每项删除。

Biome CLI 行为测试

每个新增或变更的、会调用 run_cli 或其变体的测试，都必须对完整会话进行 snapshot。使用 assert_cli_snapshot、assert_cli_snapshot_with_redactor 或基于 insta 的包装器。标量断言不能替代 snapshot。不执行 CLI 的单元测试和辅助函数测试除外。

在其他断言之后创建 snapshot，以捕获最终的文件系统、配置、输出和结果。稳定排序或对不稳定值进行脱敏；不要省略 snapshot。

参数、配置、源类型和文件系统状态相同的相关用例，应放在同一个 fixture 中，通常使用一个 snapshot。将有效、无效和边界用例放在一起。相关的多文件用例应放在同一个测试中。只有输入或测试设置不兼容时才拆分。

对于单个迁移规则，将兼容的用例放在同一个 JSONC fixture 中。若覆盖项能保留起始配置，则优先使用覆盖项。

分析器 Fixture

将规则 fixture 放在语言分析器当前的 tests/specs/<group>/<rule>/ 层级下。目录组必须与规则声明相符。

对于依赖解析器的用例，使用专门的源文件。当多个独立脚本片段共享相同配置，且不需要模块语义时，使用 .jsonc 数组。若测试需要不同的规则配置，则在子目录中使用 options.json。

诊断预期注释

测试工具会识别源代码注释中的以下标记文本：

should generate diagnostics
should not generate diagnostics

当前强制要求：

• 文件名包含 valid 但不包含 invalid 时，必须包含其中一个预期标记；
• 如果存在任一标记，实际诊断必须与其匹配；
• invalid 文件名或中性文件名没有标记也可以接受，但添加正确的标记能明确表达意图；
• .snap、.json、.jsonc 和 .md 不受有效文件标记强制检查的限制；
• HTML 系列工作区测试文件会根据原始文件内容进行检查，应使用顶层 HTML 注释。

将标记放在主要测试文件的顶部。名称中性的旁置文件无需添加标记，除非它们会作为独立测试用例进行分析。

解析器测试文件

使用解析器 crate 已有的 ok/ 和 error/ 目录。恢复行为回归测试应在格式错误的结构之后包含有效语法，以证明解析器会在预期边界恢复。

开发期间使用 just qt <parser-package> 检查 CST；不要只保留快速测试作为唯一的回归覆盖。

格式化程序测试文件

对于此次变更新增或修复的行为，使用内部规范。外部 Prettier 快照用于记录比较结果，但不能替代有针对性的内部覆盖。

对于符合条件的文件，格式化程序测试框架会在一次测试调用中执行幂等性重新格式化。出现不匹配时，请检查格式化后的输出以及显示的任何 IR。

必需的代码生成

更改的源文件	命令
.ungram grammar	just gen-grammar <lang>
格式化程序源文件	just gen-formatter <lang>
Lint 规则或辅助功能	just gen-rules 和 just gen-configuration
本地所需的绑定	just gen-bindings

根目录中的 AGENTS.md 是关于哪些产物必须提交、哪些完整输出可由 CI Autofix 提供的权威说明。

工作树有未提交更改时，不要运行 just ready：该任务会在完整验证流程前后检查 diff 是否干净。使用当前任务所需的针对性命令，然后运行 just f 和 just l。

完成检查清单

• 代码更改有针对性的持久化覆盖。
• 没有修复时，错误测试文件会失败。
• 每个已更改的快照都在筛选后接受或拒绝之前单独比较过 diff。
• 每个新增或修改的 CLI 行为测试都会创建会话快照。
• 相关 CLI 用例已合并，而不是分散在过小的快照中。
• 预期注释与测试文件的意图一致。
• 已通过 insta 清理孤立快照。
• 必需的生成产物均已包含。
• 扩大检查范围前，针对性测试已通过。

参考资料

• 主要测试指南：CONTRIBUTING.md#testing
• Insta 非交互式审查：https://github.com/mitsuhiko/insta/blob/1.48.0/CHANGELOG.md#1440
• 分析器指南：crates/biome_analyze/CONTRIBUTING.md
• CLI 快照测试框架：crates/biome_cli/tests/snap_test.rs
• 预期检查机制：crates/biome_test_utils/src/lib.rs
• 格式化程序测试框架：crates/biome_formatter_test/src/spec.rs
• 生成器任务：justfile