testing

テストスキル

テストの作成と実行に関する標準とワークフローです。すべての機能はテストされている必要があります。

開始時の宣言: 「適切なテストカバレッジを確保するため、テストスキルを使用しています。」

発動条件

• 機能またはバグ修正のための新しいテストを書くとき
• 新機能を追加するとき(テストを含める必要があります)
• 既存のテストがあるロジックを変更するとき(テストを更新する必要があります)
• 作業が完了したと主張する前
• コードをコミットする前

フレームワーク

Vitest 4 — vitest.config.ts で設定されています。

テスト構造

tests/
├── unit/          # Individual functions, utilities, components
├── integration/   # IPC, database, service interactions
├── regression/    # Regression test cases
└── e2e/           # End-to-end tests (Playwright, playwright.config.ts)

2 つのテスト環境

環境	使用する場合	ファイル命名
node(デフォルト)	メインプロセス、ユーティリティ、サービス	*.test.ts
jsdom	DOM/ブラウザに依存するコード	*.dom.test.ts

ワークフロー

ステップ 1: テスト対象を特定する

テストを書く前に、まず最もリスクの高いシナリオを一覧にします。

• 依存先が undefined を返す / 例外をスローする場合はどうなるか?
• 境界値(空のリスト、最大リトライ回数、過去のタイムスタンプ)ではどうなるか?
• 本番環境で最も壊れやすいものは何か?

ステップ 2: テストを書く

以下の品質ルールに従います。

1. コード構造ではなく振る舞いを記述する

// Wrong — describes implementation
it('should call repo.getConversation', ...)

// Correct — describes behavior
it('should return cached task without hitting repo on second call', ...)
it('should reject with error when conversation does not exist', ...)

2. すべての describe ブロックで少なくとも 1 つの失敗パスをカバーする

正常系のみのテストでは、最も危険なコードがテストされないままになります。

3. 1 つのテストにつき 1 つの振る舞い

各 it() は焦点を絞ってください。1 つのテストで expect() を 3 回より多く呼び出す場合は、一度にテストしすぎているサインです。

4. 自己チェック

テストを書いたら、対象とする中核ロジックを頭の中で削除してみてください。それでもテストが通るなら書き直してください。そのテストは何も守っていません。

5. カバレッジの穴ではなく、リスクから始める

バグを生みやすいシナリオを一覧にし、それらを最初に書きます。カバレッジは出発点ではなく結果です。

ステップ 3: テストを実行する

bun run test              # Run all tests (REQUIRED before every commit)
bun run test:coverage     # Check coverage (before opening a PR)

ステップ 4: カバレッジを検証する

カバレッジ目標: vitest.config.ts の coverage.include に一致するすべてのソースファイルで 80% 以上(現在は src/**/*.{ts,tsx} といくつかのスクリプト)。

新しいソースファイルは自動的にカバレッジ対象に含まれ、手動での設定変更は不要です。coverage.exclude のルールによって新しいファイルが誤って除外されている場合は、除外リストから削除してください。

ステップ 5: 既存のテストを更新する

ロジックを変更するときは、既存のテストの更新が必要かどうかを確認してください。

bun run test -- --reporter=verbose   # See which tests pass/fail with names

動作が意図的に変わったためにテストが失敗する場合は、テストを更新してください。予期せず失敗する場合は、原因を調査してください。

エッジケースのチェックリスト

モジュールをテストするときは、次の点を確認してください。

• null / undefined の入力が処理されている
• 空の配列/オブジェクトが処理されている
• 依存先がスローしたエラーが処理されている
• 境界値(0、-1、最大値、空文字列)
• 非同期処理(タイムアウト、リジェクト、キャンセル)

クイックチェックリスト

コードを提出する前に:

• 新機能に対応するテストケースがある
• 変更したロジックのテストが更新されている
• bun run test が通る
• テストが実装ではなく振る舞いを記述している
• describe ブロックごとに少なくとも 1 つの失敗パスがある
• 新しいソースファイルが coverage.exclude によって誤って除外されていない
• bun run test:coverage が 80% 以上の目標を満たしている

よくある間違い

間違い	正しい対応
実装の詳細をテストする	観測可能な振る舞いをテストする
正常系しかテストしない	少なくとも 1 つの失敗パスを含める
1 つの it() に 5 つ以上の expect	別々のテストに分割する
「単純な」コードのテストを省略する	単純なコードも壊れる — リスクの高い部分をテストする
「完了」と言った後にテストを書く	テストは「完了」の一部であり、後付けではない