Skip to content

README.test.md

Latest commit

 

History

History
238 lines (164 loc) · 9.76 KB

README.test.md

File metadata and controls

238 lines (164 loc) · 9.76 KB
Raw

Notion-Astroブログシステム テストガイド

このドキュメントは、プロジェクトのテスト方法を説明します。

テスト環境の設定

テストを実行するには、まず必要なパッケージをインストールしてください：

pnpm install

テストの種類

このプロジェクトでは主に以下の3種類のテストを実装しています：

  1. ユニットテスト: 個別の関数やコンポーネントの機能をテスト
  2. 統合テスト: 複数のモジュールの連携をテスト
  3. E2Eテスト: ブラウザ上での実際の動作をテスト

テストコマンド

ユニットテストと統合テスト

# すべてのテストを実行
pnpm test

# テストをウォッチモードで実行（変更を検知して再実行）
pnpm test:watch

# カバレッジレポートを生成
pnpm test:coverage

E2Eテスト

E2Eテストを実行するには、Playwrightのインストールが必要です：

# Playwrightをインストール
pnpm add -D @playwright/test
npx playwright install

# E2Eテストを実行
pnpm test:e2e

# UIモードでE2Eテストを実行（ブラウザが表示される）
pnpm test:e2e:ui

テストファイルの構造

/
├── src/
│   ├── test/
│   │   ├── mocks/             # テスト用のモックデータ
│   │   ├── setup.ts           # テスト環境のセットアップ
│   │   ├── integration/       # 統合テスト
│   │   └── e2e/               # E2Eテスト
│   ├── lib/
│   │   └── notion.test.ts     # NotionAPIクライアントのテスト
│   └── components/
│       └── NotionBlock.test.tsx # コンポーネントのテスト
├── vitest.config.ts           # Vitestの設定
└── playwright.config.ts       # Playwrightの設定（必要に応じて作成）

テスト戦略

Notionライブラリのテスト

src/lib/notion.tsのテストでは、以下の点に注目しています：

  1. APIの正しい呼び出し: Notion APIが正しいパラメータで呼び出されるか
  2. データの整形: API応答から正しくデータが整形されるか
  3. エラーハンドリング: API障害時に適切に処理されるか
  4. キャッシュ機能: キャッシュが期待通りに動作するか

コンポーネントのテスト

src/components/NotionBlock.tsxのテストでは、以下の点に注目しています：

  1. 正しいレンダリング: 各タイプのブロックが正しくレンダリングされるか
  2. リッチテキスト処理: テキストの装飾が正しく適用されるか
  3. ネストされたコンテンツ: 子要素を持つブロックが正しく表示されるか
  4. エッジケース: サポートされていないブロックタイプや空のコンテンツが適切に処理されるか

統合テスト

統合テストでは、Notionからデータを取得してコンポーネントでレンダリングするまでの一連のフローをテストします。

E2Eテスト

E2Eテストでは、実際のブラウザ上での動作を検証します：

  1. ページナビゲーション: 各ページが正しく表示されるか
  2. レスポンシブデザイン: モバイルとデスクトップで正しく表示されるか
  3. ユーザーインタラクション: リンクやボタンが正しく機能するか

モックデータ

テストでは、src/test/mocks/notionData.tsに定義されたモックデータを使用しています。Notion APIのレスポンスをシミュレートするためのデータを提供します。

CI/CD統合

GitHubでのCIワークフロー例：

# .github/workflows/test.yml
name: Tests

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 20
      - name: Install dependencies
        run: npm ci
      - name: Run tests
        run: npm test
      - name: Run E2E tests
        run: npx playwright install --with-deps && npm run test:e2e

テストカバレッジ目標

このプロジェクトでは、以下のテストカバレッジ目標を設定しています：

  • ユニットテスト: コードベースの80%以上をカバー
  • 統合テスト: 主要なユーザーフローをすべてカバー
  • E2Eテスト: 重要なページとインタラクションをカバー

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

  1. 独立したテスト: 各テストは他のテストに依存せず独立して実行できるようにする
  2. 高速なテスト: テストは可能な限り高速に実行されるべき（特にユニットテスト）
  3. モックの適切な使用: 外部依存（APIなど）は適切にモック化する
  4. 実際のユースケース: 実際のユースケースに基づいたテストを書く
  5. エッジケースのカバー: 境界値や異常系のテストを忘れずに実装する

トラブルシューティング

テストが失敗する場合

  1. 依存関係の確認: すべての依存関係が正しくインストールされているか確認
  2. 環境変数: 必要な環境変数が設定されているか確認（テスト用の.env.testを用意する）
  3. タイミング問題: 非同期テストにおいて、適切にawaitが使われているか確認
  4. モックの再確認: APIレスポンスなどのモックが最新の実装と一致しているか確認

テストの実行が遅い場合

  1. 並列実行: Vitestの並列実行設定を確認
  2. テストの粒度: 大きすぎるテストを分割する
  3. 不要なセットアップの削減: 各テストで必要最小限のセットアップのみを行う

新機能追加時のテスト戦略

新機能を追加する際は、TDD（テスト駆動開発）アプローチを推奨します：

  1. 失敗するテストを書く: 新機能の要件を満たすテストを先に書く
  2. コードを実装: テストが通るようにコードを実装する
  3. リファクタリング: コードの品質を改善しながらテストが通ることを確認

Notionブロックの追加サポート時のテスト

新しいNotionブロックタイプをサポートする際は、以下のテストを追加してください：

  1. モックデータの追加: notionData.tsに新しいブロックタイプのモックを追加
  2. レンダリングテスト: 新しいブロックが正しくレンダリングされることを確認するテスト
  3. エッジケース: 特殊なケース（空のコンテンツ、特殊な書式など）に対するテスト

APIバージョン変更時の対応

Notion APIが更新された場合は、以下の手順でテストを更新してください：

  1. モックの更新: 新しいAPIレスポンス形式に合わせてモックを更新
  2. テストケースの見直し: 新機能や変更点に対応するテストケースの追加
  3. 回帰テスト: 既存機能が引き続き動作することを確認

パフォーマンステスト

頻繁に更新される大規模なNotionドキュメントを扱う場合、以下のパフォーマンステストを実施することを推奨します：

  1. レンダリング速度: 大量のブロックがある場合のレンダリング時間測定
  2. APIコール最適化: キャッシュ機構が効果的に動作しているか確認
  3. メモリ使用量: 大きなページ処理時のメモリ使用量を監視

アクセシビリティテスト

アクセシビリティを確保するため、以下のテストを追加することを検討してください：

  1. axeプラグイン: Playwrightとaxeを組み合わせたアクセシビリティテスト
  2. キーボードナビゲーション: キーボードのみでの操作が可能か確認するテスト
  3. スクリーンリーダー互換性: スクリーンリーダーで正しく読み上げられるか確認

Typescriptとの連携

  1. 型チェック: テストコードも厳格な型チェックを適用する
  2. 型定義テスト: 重要な型定義が正しく機能することをチェックするテスト
  3. Notionの型定義: Notion APIのレスポンス型定義が常に最新の状態に保たれているか確認

スナップショットテスト

Vitestのスナップショットテスト機能を使って、コンポーネントのレンダリング結果が期待通りであることを確認できます：

it('コンポーネントが正しくレンダリングされること（スナップショット）', () => {
  const { container } = render(<NotionBlock block={paragraphBlock} />);
  expect(container).toMatchSnapshot();
});

スナップショットテストは、以下の場合に特に有効です：

  1. レンダリング結果の変更を検出
  2. リグレッションの防止
  3. 複雑なコンポーネントの視覚的な確認

定期的なテストメンテナンス

テストコードは定期的にメンテナンスする必要があります：

  1. モックの更新: 実装の変更に合わせてモックを更新
  2. 非推奨APIの更新: 非推奨になったテストAPIを最新のものに置き換え
  3. テストカバレッジの改善: カバレッジが低い領域に新しいテストを追加

これらのガイドラインに従うことで、プロジェクトの品質と安定性を維持することができます。