テストの期待値を仕様に寄せると、レビューは終わりやすくなる
テストは、通ればよいわけではありません。 期待値が仕様からズレていると、テストは「動くけれど信じにくいもの」になります。
今回のエンジン側リポジトリでは、round-7のレビューで、MockEngineの完全実装化や実行権限の引き締めだけでなく、アサーションそのものを仕様寄りに整えることが重要だと改めて確認しました。
期待値が弱いと何が起きるか
期待値が曖昧なテストは、実装の変化に追従できません。 表面上は緑でも、何を保証しているのかが薄いので、レビューでも判断しづらくなります。
特にモックを使うテストでは、入力が適当でも通ってしまうことがあります。 その結果、テストが「仕様の説明」ではなく「たまたま通る確認」に近づいてしまいます。
仕様に寄せるとはどういうことか
仕様に寄せるとは、実装の細部ではなく、利用者が期待する振る舞いをそのまま書くことです。 つまり、MockEngineが何を返すかではなく、どんな条件でどんな結果が必要かを明示することです。
この視点でアサーションを置き直すと、テストは読みやすくなります。 レビューする側も「このテストが守るべきもの」を短時間で理解できます。
Testing Libraryのguiding principleは、「テストがソフトウェアの使われ方に似ているほど信頼できる」という考え方です。 この考え方をEngineやドメインロジックのテストに置き換えると、期待値は内部実装ではなく、外から見た契約に寄せるべきだと分かります。
たとえば、MockEngineの内部メソッドが呼ばれた回数だけを見るのではなく、次のような契約を見る方が強いです。
合法手なら結果が受理される
非合法手なら拒否される
失敗時にlastErrorが読める
dispose後に追加処理が走らない
検索結果が空ならbestMove: nullとして扱われる
こうすると、テストは実装の監視ではなく仕様の説明になります。
完全実装モックとの相性
完全実装モックは、仕様に寄せた期待値と相性がいいです。 モックが中途半端だと、期待値も中途半端になりやすいからです。
今回の修正では、Partial<IEngine> を使うよりも、実際の振る舞いに近いMockEngineを置く方が、期待値を整理しやすいことが分かりました。 モックが強くなると、期待値も自然と締まります。
Vitestの公式ガイドでも、mockの状態をテスト間で残さないことが重要だと説明されています。 仕様に寄せたテストでも、前のテストの呼び出し履歴や差し替えた戻り値が残ると、期待値は簡単に歪みます。
後片付けは目的に応じて選びます。呼び出し履歴だけを消すならmockClear、実装も既定状態へ戻すならmockReset、spyで差し替えた元のメソッドまで戻すならmockRestoreです。
なので、契約テストでは次をセットにします。
fixtureを仕様の言葉で作る
mockはinterfaceを満たす
testごとに必要な範囲のmock stateをリセットする
アサーションは副作用ではなく観測できる結果を見る
非同期の断言は「実行された」ことまで確認する
期待値を仕様へ寄せても、断言そのものを待たなければテストは契約を守れません。Vitestではexpect.pollを含む非同期の断言をawaitし忘れると、Vitest 3以降は警告付きで失敗します。
非同期のテストでは、次の順で点検します。
resolves、rejects、expect.pollの結果をawaitしているか
callback内の断言が実際に実行される構造か
成功だけでなく、失敗・取消・cleanup後に起きないことも見ているか
truthyだけで足りるのか、具体値・呼び出し回数・引数まで必要なのか
toBeTruthyは「真として扱える値」であればよいときに向くmatcherです。値の種類や内容が契約に含まれるなら、toBeやtoEqual、呼び出し回数・引数の断言など、仕様を直接表すmatcherを選びます。
参考: https://vitest.dev/api/expect.html
実行権限を締める意味
.claude/settings.local.jsonのpermission rulesを引き締めたのも、同じ文脈です。 テストが仕様に寄るほど、実行環境の自由度はむしろ減らした方が分かりやすくなります。
なんでも通る環境は便利ですが、レビュー時にはノイズになります。 必要なものだけを許可する方が、テストと実装の境界が見えやすいです。
Claude Codeの現行設定では、ツール利用をallow、ask、denyのルールで分けられます。読み取りなど安全な操作だけを自動許可し、変更や外部作用を伴う操作は確認または拒否へ寄せると、レビュー対象の境界を保ちやすくなります。
レビューを終わらせる判断基準
レビューが終わるかどうかは、変更量の多さより、期待値が仕様をきちんと表しているかで決まります。 仕様に近いテストは、見直しがしやすく、次の変更でも壊れにくいです。
今回のround-7で得た感覚は、テストは「細かく正しい」だけでなく、「仕様として読める」ことが重要だということでした。
レビュー時の判断基準は、次のように固定できます。
テスト名だけで仕様が分かる
fixtureが現実の入力に近い
mockが本体契約から逃げていない
期待値が「実装都合」ではなく「外から見える振る舞い」を見ている
失敗時に何が壊れたか説明できる
この基準を満たしていると、レビューは「もっと細かく直して」ではなく「この契約ならOK」と判断しやすくなります。
まとめ
テストの期待値を仕様に寄せると、レビューは終わりやすくなります。 モックを完全実装に近づけ、許可範囲を締め、アサーションを仕様の言葉に揃える。
そうすると、テストは単なる確認ではなく、仕様のドキュメントになります。 それが、レビューを前に進める一番素直なやり方です。
参考資料
調査確認日: 2026-06-28
注意事項
私は実装コードを直接書かず、AIへの設計指示と結果の確認・採否の判断を担当します。本稿の一般化した手順やサンプルは、対象環境への適用と検証が必要です。本文で明示した作業記録と、提案する確認項目を分けて読んでください。バージョン、料金、提供条件、ブラウザや依存パッケージの仕様は変わるため、適用前に公式情報と対象環境で再確認が必要です。
公開前には、認証情報、内部URL、個人情報、完全な設定値が含まれていないことを確認し、小さな検証とロールバック手順を用意してください。