vitest-best-practices

Vitest のベストプラクティス

このスキルを適用するタイミング

次のいずれかの状況に当てはまる場合は、このスキルを使用してください。

ファイルパターン

• *.test.ts、*.spec.ts などのテストファイルを扱う場合
• TypeScript／JavaScript モジュールの新しいテストファイルを作成する場合
• 既存の Vitest テストスイートをレビューする場合

ユーザーの意図を示すキーワード

• ユーザーが Vitest、テスト、TDD、BDD、ユニットテスト、統合テストについて言及している
• ユーザーがテストの作成、テストカバレッジの追加、失敗するテストの修正、テストのリファクタリングを依頼している
• ユーザーがモック、スタブ、アサーション、テストのパフォーマンス、テストの構成について話している

コードのコンテキスト

• vitest（describe、it、expect、vi）からインポートしているファイル
• テストのセットアップ／後処理コード（beforeEach、afterEach、beforeAll、afterAll）
• vi.mock()、vi.spyOn()、vi.fn() を使ったモック／スパイの実装
• アサーションチェーン（expect(...).toEqual()、.toBe()、.toThrow() など）

一般的なタスク

• 既存の機能に対する新しいテストケースの作成
• 明確さやパフォーマンスを向上させるためのテストのリファクタリング
• 不安定なテストや失敗するテストのデバッグ
• テストカバレッジや保守性の向上
• ベストプラクティスへの準拠を確認するためのテストコードのレビュー

このスキルを使用しない場合

• Playwright／Cypress を使ったエンドツーエンドテストを作成する場合（対象範囲が異なります）
• テストではなく、実装コードのみを扱うタスクの場合

このスキルで扱う内容

このスキルでは、次の内容について包括的なガイダンスを提供します。

1. テストの構成：ファイルの配置、命名規則、グループ化の方法
2. AAA パターン：明確にするための Arrange、Act、Assert の構成
3. パラメーター化テスト：複数のバリエーションをテストするための it.each() の使用
4. エラー処理：例外、エッジケース、フォールトインジェクションのテスト
5. アサーション：厳密なアサーション（toEqual、toStrictEqual、toThrow）の選択
6. テストダブル：フェイク、スタブ、モック、スパイの使い分け
7. 非同期テスト：Promise、async/await、タイマー、並行テスト
8. パフォーマンス：高速なテスト、高コストな処理の回避、クリーンアップのパターン
9. Vitest 固有の機能：カバレッジ、ウォッチモード、ベンチマーク、型テスト、セットアップファイル
10. スナップショットテスト：スナップショットを効果的に使うタイミングと方法

使い方

このスキルでは、コンテキストの使用量を最小限に抑えるため、段階的に情報を開示する構成を採用しています。

1. 概要から始める（AGENTS.md）

すべてのルールを一行ずつ簡潔にまとめた概要を確認するには、AGENTS.md を読んでください。

2. 必要に応じて該当するルールを読み込む

関連する最適化を特定したら、対応するリファレンスファイルを読み込み、実装の詳細なガイダンスを確認してください。

基本的なパターン：

• organization.md
• aaa-pattern.md
• parameterized-tests.md
• error-handling.md
• assertions.md
• test-doubles.md

応用トピック：

• async-testing.md
• performance.md
• vitest-features.md
• snapshot-testing.md

3. パターンを適用する

各リファレンスファイルには次の内容が含まれています。

• ❌ アンチパターンを示す不適切な例
• ✅ 最適な実装を示す適切な例
• パターンが重要な理由の説明

簡単な例

このスキルを使うと、わかりにくいテストを明確で保守しやすいテストに改善できます。

変更前（わかりにくい）：

test('product test', () => {
  const p = new ProductService().add({name: 'Widget'});
  expect(p.status).toBe('pendingApproval');
});

変更後（このスキルで最適化）：

describe('ProductService', () => {
  describe('Add new product', () => {
    it('should have status "pending approval" when no price is specified', () => {
      // Arrange
      const productService = new ProductService();

      // Act
      const newProduct = productService.add({name: 'Widget'});

      // Assert
      expect(newProduct.status).toEqual('pendingApproval');
    });
  });
});

主な原則

• 巧妙さより明確さ：テストはすぐに理解できるようにします
• フラットな構造：describe ブロックの深いネストを避けます
• 概念ごとにアサーションを1つ：テストでは単一の振る舞いに焦点を当てます
• 厳密なアサーション：必要に応じて toBe より toEqual を、toEqual より toStrictEqual を優先します
• モックは最小限に：実用的な場合は実際の実装を使用します
• 高速な実行：効率的なセットアップ／後処理でテストをすばやく実行できるようにします