testing-best-practices

テストのベストプラクティス

信頼性と保守性の高いテストスイートを実現するための、単体テスト、統合テスト、TDD の原則です。TypeScript と Jest/Vitest を使用し、7 つのカテゴリにわたる 34 のルールをまとめています。

メタデータ

• バージョン： 2.0.0
• ルール数： 7 つのカテゴリにわたる 34 のルール
• ライセンス： MIT

適用する場面

次のような場合に、これらのガイドラインを参照してください。

• 単体テストまたは統合テストを作成するとき
• テストコードの品質をレビューするとき
• テストカバレッジの戦略を改善するとき
• テストインフラストラクチャを設定するとき
• 不安定なテストや遅いテストをデバッグするとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	テスト構造	重大	struct-
2	テストの分離	重大	iso-
3	アサーション	高	assert-
4	テストデータ	高	data-
5	モック	中	mock-
6	カバレッジ	中	cov-
7	パフォーマンス	低	perf-

クイックリファレンス

1. テスト構造（重大）

• struct-aaa-pattern - Arrange、Act、Assert パターン
• struct-descriptive-names - 説明的なテスト名
• struct-one-assertion - テストごとに 1 つの論理アサーション
• struct-describe-it - describe/it によるテストスイートの整理
• struct-given-when-then - 適切な場面での BDD スタイル
• struct-setup-teardown - 適切なセットアップとティアダウン

2. テストの分離（重大）

• iso-independent-tests - テストを独立して実行できるようにする
• iso-no-shared-state - 変更可能な状態を共有しない
• iso-deterministic - 毎回同じ結果になるようにする
• iso-no-order-dependency - 任意の順序で実行できるようにする
• iso-cleanup - テスト後にクリーンアップする
• iso-test-doubles - テストダブルを戦略的に使用する

3. アサーション（高）

• assert-specific - 具体的なアサーションを使用する
• assert-meaningful-messages - 失敗時に役立つメッセージを表示する
• assert-expected-actual - 期待値を先に記述する
• assert-no-magic-numbers - 名前付き定数を使用する
• assert-custom-matchers - ドメインロジックにカスタムマッチャーを使用する

4. テストデータ（高）

• data-factories - テストデータにファクトリーを使用する
• data-builders - 複雑なオブジェクトにビルダーパターンを使用する
• data-faker - 現実的な偽データを生成する
• data-minimal - テストデータを最小限にする
• data-realistic - 現実的なエッジケースを用意する
• data-fixtures - テストフィクスチャを管理する

5. モック（中）

• mock-boundaries - 境界でのみモックを使用する
• mock-verify-interactions - 重要なモック呼び出しを検証する
• mock-minimal - モックを過剰に使用しない
• mock-realistic - MSW で現実的なモックの振る舞いを実現する

6. カバレッジ（中）

• cov-meaningful - 意味のあるカバレッジを重視する
• cov-edge-cases - エッジケースと境界値を網羅する
• cov-unhappy-paths - エラーシナリオをテストする
• cov-not-100-percent - カバレッジ 100% を目標にしない

7. パフォーマンス（低）

• perf-fast-unit - 単体テストを高速に保つ（1 件あたり 50 ミリ秒未満）
• perf-parallel - テストを並列実行する
• perf-test-organization - すばやくフィードバックを得られるようにテストを整理する

基本ガイドライン

AAA パターン（Arrange、Act、Assert）

it('calculates total with discount', () => {
  // Arrange
  const cart = new ShoppingCart();
  cart.addItem({ name: 'Book', price: 20 });
  cart.applyDiscount(0.1);

  // Act
  const total = cart.getTotal();

  // Assert
  expect(total).toBe(18);
});

説明的なテスト名

// ✅ Describes behavior and scenario
describe('UserService.register', () => {
  it('creates user with hashed password', () => {});
  it('throws ValidationError when email is invalid', () => {});
  it('sends welcome email after successful registration', () => {});
});

テストの分離

// ✅ Each test sets up its own data
beforeEach(() => {
  mockRepository = { save: vi.fn(), find: vi.fn() };
  service = new OrderService(mockRepository);
});

使用方法

詳しい説明については、各ルールファイルを参照してください。

rules/struct-aaa-pattern.md
rules/iso-independent-tests.md
rules/mock-boundaries.md
rules/cov-meaningful.md

参考資料

• Vitest ドキュメント
• Jest ドキュメント
• Testing Library
• MSW（Mock Service Worker）

コンパイル済みドキュメント全文

すべてのルールを詳しく解説したガイドについては、AGENTS.md を参照してください。