testing-codegen

テストとコード生成

変更した動作を検証できる、最も対象を絞ったテストを選びます。共有インフラストラクチャや統合に関するリスクが正当化する場合に限り、テストの範囲を広げます。

テストの選択

変更	最初に実行するテスト
リントルール	just test-lintrule <ruleName>
1 つのクレート	cargo test -p <crate> またはそのクレートの対象を絞ったテストターゲット
パーサーまたはフォーマッターの調査	just qt <package>
CLI の移行	対象を絞った biome_cli の移行テスト
ドキュメントのコード	just test-doc

テストの診断出力が必要な場合に限り、-- --show-output または --nocapture を使用します。

クイックテストは、CST、フォーマッター IR、または 1 つのアナライザークエリを調べるための一時的な作業場所です。継続的に維持する動作は、作業を終える前にサブシステムの通常のフィクスチャディレクトリに配置します。

スナップショットのワークフロー

対象を絞ったテストを実行して、保留中のスナップショットを作成します。無関係なテストの失敗は切り分けて扱います。スナップショットを手動で更新、追加、削除しないでください。insta に任せます。

エージェントは、TTY を必要とするフィルターなしの cargo insta review を実行してはいけません。TTY のないエージェントシェルでは、cargo-insta 1.44+ はプロンプトを表示せず、フィルターされた --snapshot の差分を出力します。

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

差分全体を確認した後、そのスナップショットだけを承認または却下します。

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

変更ごとにこれを繰り返し、保留中のスナップショットを再度一覧表示してから、テストを再実行します。レビューでは、差分で動作を確認します。テストに合格しても、出力がスナップショットと一致していることしか証明されません。

フィルターなしの cargo insta accept または cargo insta reject、cargo insta test --accept、cargo insta test --force-update-snapshots、INSTA_UPDATE=always／force は使用しないでください。個別のレビューを省略し、無関係な作業を変更する可能性があります。

孤立したスナップショット

孤立していると思われるスナップショットを手動で削除しないでください。パッケージ、ターゲット、テストのフィルターを指定せず、ワークスペース全体のスナップショットスイートを実行した後に限り、安全に削除できます。

cargo insta test --workspace --unreferenced delete

対象を絞った実行では、--unreferenced warn または --unreferenced reject を使用してください。テストの選択が不完全だと、スナップショットが孤立していることを証明できません。全体を実行したときの削除は、すべて確認してください。

Biome CLI の動作テスト

run_cli またはそのバリアントを呼び出す新規または変更済みのテストでは、必ずセッション全体のスナップショットを作成してください。assert_cli_snapshot、assert_cli_snapshot_with_redactor、または insta ベースのラッパーを使用します。スカラー値のアサーションでスナップショットを代用することはできません。CLI を実行しないユニットテストとヘルパーテストは対象外です。

ほかのアサーションの後にスナップショットを作成し、最終的なファイルシステム、設定、出力、結果を記録します。順序を安定させるか、不安定な値をマスキングしてください。スナップショットを省略してはいけません。

引数、設定、ソースの種類、ファイルシステムの状態が同じ関連ケースは、1 つのフィクスチャにまとめ、通常は 1 つのスナップショットにします。有効、無効、境界値のケースをまとめて含めてください。関連する複数ファイルのケースは 1 つのテストにまとめます。互換性のない入力やテスト設定の場合に限り、分割してください。

1 つの移行ルールについては、互換性のあるケースを 1 つの JSONC フィクスチャにまとめます。開始時の設定を維持できる場合は、オーバーライドを優先してください。

アナライザーフィクスチャ

ルールのフィクスチャは、言語アナライザーの現在の tests/specs/<group>/<rule>/ 階層に配置します。ディレクトリのグループは、ルール宣言と一致させてください。

パーサーに依存するケースには、対象を絞ったソースファイルを使用します。同じ設定を共有し、モジュールの意味論が不要な複数の独立したスクリプトスニペットには、.jsonc 配列を使用します。異なるルール設定が必要なテストでは、サブディレクトリに options.json を配置します。

診断の期待値コメント

テストユーティリティは、ソースコメント内の次のマーカーテキストを認識します。

should generate diagnostics
should not generate diagnostics

現在の適用ルール：

• ファイル名に valid が含まれ、invalid が含まれない場合、期待値マーカーを1つ含める必要があります。
• どちらかのマーカーがある場合、実際の診断はマーカーと一致する必要があります。
• invalid を含むファイル名、または中立的なファイル名でマーカーがない場合は受け入れられますが、正しいマーカーを追加すると意図が明確になります。
• .snap、.json、.jsonc、.md は、有効なファイルに必須のマーカーを付けるチェックの対象外です。
• HTML 系のワークスペースフィクスチャは生のファイル内容をチェックするため、ファイル先頭の HTML コメントを使用してください。

マーカーは主要なフィクスチャの先頭に置いてください。中立的な名前のサイドカーファイルは、独立したケースとして解析される場合を除き、マーカーを付ける必要はありません。

パーサーフィクスチャ

パーサークレートで確立されている ok/ および error/ ディレクトリを使用してください。リカバリーのリグレッションでは、不正な構文の後に有効な構文を含め、パーサーが意図した境界で解析を再開することを確認してください。

開発中に CST を調べるには just qt <parser-package> を使用してください。このクイックテストだけをリグレッション対策として残さないでください。

フォーマッターフィクスチャ

変更によって導入または修正された動作には、内部仕様を使用してください。外部の Prettier スナップショットは比較結果を記録するものですが、焦点を絞った内部テストの代わりにはなりません。

対象ファイルでは、フォーマッターハーネスが1回のテスト実行中に冪等性を確認する再フォーマットを行います。不一致があった場合は、フォーマット後の出力と表示された IR の両方を調べてください。

必須のコード生成

変更したソース	コマンド
.ungram 文法	just gen-grammar <lang>
フォーマッターのソース	just gen-formatter <lang>
リントルールまたはアシスト	just gen-rules および just gen-configuration
ローカルで必要なバインディング	just gen-bindings

どのアーティファクトをコミットする必要があるか、また CI Autofix でどの全出力を生成できるかは、ルートの AGENTS.md を正式な情報源として参照してください。

作業ツリーに未コミットの変更がある状態で just ready を実行しないでください。このレシピは、検証シーケンス全体の前後で差分がクリーンであることを確認します。現在のタスクで必要な対象を絞ったコマンドを実行し、その後 just f と just l を実行してください。

完了チェックリスト

• コードの変更に、対象を絞った永続的なテストカバレッジがある。
• 修正がなければバグフィクスチャが失敗する。
• 変更した各スナップショットを、フィルターを使った承認または却下の前に個別に差分確認した。
• 新規または変更した 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