typescript-e2e-testing

E2E テストスキル

E2E テストでは、Docker を介して実際のインフラストラクチャを使用し、ユーザーの視点からワークフロー全体を検証します。

---

ワークフロー

包括的な手順ガイドが必要な場合は、適切なワークフローを使用してください。

ワークフロー	使用する場面
E2E テストのセットアップ	新規または既存のプロジェクトに E2E インフラストラクチャをセットアップする
E2E テストの作成	適切な GWT パターンで新しい E2E テストケースを作成する
E2E テストのレビュー	既存のテストの品質と正確性を確認する
E2E テストの実行	適切な検証を行いながらテストを実行する
E2E テストのデバッグ	失敗するテストを体系的に修正する
E2E テストの最適化	テストスイートのパフォーマンスを改善する

ワークフロー選択ガイド

重要：E2E テストのタスクを開始する前に、ユーザーの意図を特定し、適切なワークフローを読み込んでください。

ユーザーの意図を検出 → ワークフローを選択

ユーザーの発言・要望	読み込むワークフロー	ファイル
「E2E テストをセットアップして」「docker-compose を設定して」「プロジェクトに E2E を追加して」「テストヘルパーを作成して」	セットアップ	workflows/setup/workflow.md
「E2E テストを書いて」「統合テストを追加して」「このエンドポイントをテストして」「e2e-spec を作成して」	作成	workflows/writing/workflow.md
「E2E テストをレビューして」「テストの品質を確認して」「テストを監査して」「このテストは正しい？」	レビュー	workflows/review/workflow.md
「E2E テストを実行して」「テストを実行して」「Docker を起動してテストして」「テストが通るか確認して」	実行	workflows/running/workflow.md
「E2E テストを修正して」「テストをデバッグして」「テストが失敗している」「不安定なテスト」「接続エラー」	デバッグ	workflows/debugging/workflow.md
「E2E テストを高速化して」「テストを最適化して」「テストが遅い」「テスト時間を短縮して」	最適化	workflows/optimize/workflow.md

ワークフロー実行プロトコル

1. 必ず最初にワークフローファイルを読み込む - 作業に着手する前に、ワークフロー全体を読みます
2. 各ステップを順番に実行する - 次に進む前にチェックポイントを完了します
3. 指示に従ってナレッジファイルを読み込む - 各ワークフローで、読み込むべき references/ ファイルが指定されています
4. 完了後に準拠状況を確認する - 品質を確保するため、関連する参照ファイルを再度読みます

重要：各ワークフローには、タスクの実行前と完了後に references/ フォルダーから関連する知識を読み込む指示が含まれています。

---

ナレッジベースの構成

references/
├── common/              # Shared testing fundamentals
│   ├── knowledge.md     # Core E2E concepts and test pyramid
│   ├── rules.md         # Mandatory testing rules (GWT, timeouts, logging)
│   ├── best-practices.md # Test design and cleanup patterns
│   ├── test-case-creation-guide.md # GWT templates for all scenarios
│   ├── nestjs-setup.md  # NestJS app bootstrap and Jest config
│   ├── debugging.md     # VS Code config and log analysis
│   └── examples.md      # Comprehensive examples by category
│
├── kafka/               # Kafka-specific testing
│   ├── knowledge.md     # Why common approaches fail, architecture
│   ├── rules.md         # Kafka-specific testing rules
│   ├── test-helper.md   # KafkaTestHelper implementation
│   ├── docker-setup.md  # Redpanda/Kafka Docker configs
│   ├── performance.md   # Optimization techniques
│   ├── isolation.md     # Pre-subscription pattern details
│   └── examples.md      # Kafka test examples
│
├── postgres/            # PostgreSQL-specific testing
│   ├── knowledge.md     # PostgreSQL testing concepts
│   ├── rules.md         # Cleanup, transaction, assertion rules
│   ├── test-helper.md   # PostgresTestHelper implementation
│   └── examples.md      # CRUD, transaction, constraint examples
│
├── mongodb/             # MongoDB-specific testing
│   ├── knowledge.md     # MongoDB testing concepts
│   ├── rules.md         # Document cleanup and assertion rules
│   ├── test-helper.md   # MongoDbTestHelper implementation
│   ├── docker-setup.md  # Docker and Memory Server setup
│   └── examples.md      # Document and aggregation examples
│
├── redis/               # Redis-specific testing
│   ├── knowledge.md     # Redis testing concepts
│   ├── rules.md         # TTL and pub/sub rules
│   ├── test-helper.md   # RedisTestHelper implementation
│   ├── docker-setup.md  # Docker configuration
│   └── examples.md      # Cache, session, rate limit examples
│
└── api/                 # API testing (REST, GraphQL, gRPC)
    ├── knowledge.md     # API testing concepts
    ├── rules.md         # Request/response assertion rules
    ├── test-helper.md   # Auth and Supertest helpers
    ├── examples.md      # REST, GraphQL, validation examples
    └── mocking.md       # MSW and Nock external API mocking

タスク別クイックリファレンス

ヒント：詳しい手順ガイドについては、上記のワークフローセクションを使用してください。

新しい E2E 構成のセットアップ

ワークフロー：E2E テストのセットアップ

1. references/common/knowledge.md を読み、E2E の基礎を理解します
2. references/common/nestjs-setup.md を読み、プロジェクトのセットアップ方法を確認します
3. 必要に応じて、技術ごとの docker-setup.md ファイルを読みます

テストケースの作成

ワークフロー：E2E テストの作成

1. 必須：references/common/rules.md を読み、GWT パターンとタイムアウトを確認します
2. references/common/test-case-creation-guide.md を読み、テンプレートを確認します
3. 技術ごとのファイルを読みます。
   • Kafka：references/kafka/knowledge.md → test-helper.md → isolation.md
   • PostgreSQL：references/postgres/rules.md → test-helper.md
   • MongoDB：references/mongodb/rules.md → test-helper.md
   • Redis：references/redis/rules.md → test-helper.md
   • API：references/api/rules.md → test-helper.md

テスト品質のレビュー

ワークフロー：E2E テストのレビュー

1. references/common/rules.md を読み、必須パターンに照らして確認します
2. references/common/best-practices.md を読み、品質基準を確認します
3. 技術ごとの rules.md ファイルを読みます

E2E テストを実行する

ワークフロー：E2E テストの実行

1. Docker インフラストラクチャが稼働していることを確認します
2. npm run test:e2e > /tmp/e2e-${E2E_SESSION}-output.log 2>&1 でテストを順番に実行します
3. テストが失敗した場合は、失敗時の手順に従います

失敗したテストをデバッグする

ワークフロー：E2E テストのデバッグ

1. references/common/debugging.md を読みます
2. 進捗を記録するファイル /tmp/e2e-${E2E_SESSION}-failures.md を作成します
3. 一度に 1 つのテストを修正します

テストのパフォーマンスを最適化する

ワークフロー：E2E テストの最適化

1. references/common/best-practices.md のパフォーマンスパターンを読みます
2. Kafka のテストでは references/kafka/performance.md を読みます
3. 変更を加える前にベースラインを測定します

例

• 一般的なパターンについては references/common/examples.md を読みます
• 詳細なシナリオについては、テクノロジー固有の examples.md を読みます

---

基本原則

0. コンテキスト効率（出力を一時ファイルに保存）

E2E テストの出力は必ず一時ファイルにリダイレクトし、コンソールには出力しないでください。E2E の出力は冗長で、エージェントのコンテキストを膨らませます。

重要：出力は一時ファイルのみにリダイレクトしてください（コンソールには出力しないでください）。競合を防ぐため、一意のセッション ID を使用します。

# Generate unique session ID at start of debugging session
export E2E_SESSION=$(date +%s)-$$

# Standard pattern - redirect to file only (no console output)
npm run test:e2e > /tmp/e2e-${E2E_SESSION}-output.log 2>&1

# Read summary only (last 50 lines)
tail -50 /tmp/e2e-${E2E_SESSION}-output.log

# Get failure details
grep -B 2 -A 15 "FAIL\|✕" /tmp/e2e-${E2E_SESSION}-output.log

# Cleanup when done
rm -f /tmp/e2e-${E2E_SESSION}-*.log /tmp/e2e-${E2E_SESSION}-*.md

一時ファイル（${E2E_SESSION} はエージェントごとに一意です）：

• /tmp/e2e-${E2E_SESSION}-output.log - テスト出力全体
• /tmp/e2e-${E2E_SESSION}-failures.log - フィルター済みの失敗出力
• /tmp/e2e-${E2E_SESSION}-failures.md - 1 つずつ修正するための進捗記録ファイル
• /tmp/e2e-${E2E_SESSION}-debug.log - デバッグ実行
• /tmp/e2e-${E2E_SESSION}-verify.log - 検証実行

1. 実際のインフラストラクチャ

Docker 経由で実際のサービスを対象にテストします。E2E テストでデータベースやメッセージブローカーをモックしないでください。

2. GWT パターン（必須）

すべての E2E テストは Given-When-Then に従う必要があります：

it('should create user and return 201', async () => {
  // GIVEN: Valid user data
  const userData = { email: '[email protected]', name: 'Test' };

  // WHEN: Creating user
  const response = await request(httpServer)
    .post('/users')
    .send(userData)
    .expect(201);

  // THEN: User created with correct data
  expect(response.body.data.email).toBe('[email protected]');
});

3. テストの分離

各テストは独立している必要があります：

• beforeEach でデータベースの状態をクリーンアップします
• 一意の識別子（コンシューマーグループ、トピック）を使用します
• 非同期操作の完了を待ちます

4. 具体的なアサーション

存在するかどうかだけでなく、正確な値をアサートします：

// WRONG
expect(response.body.data).toBeDefined();

// CORRECT
expect(response.body).toMatchObject({
  code: 'SUCCESS',
  data: { email: '[email protected]', name: 'Test' }
});

---

プロジェクト構成

project-root/
├── src/
├── test/
│   ├── e2e/
│   │   ├── feature.e2e-spec.ts
│   │   ├── setup.ts
│   │   └── helpers/
│   │       ├── test-app.helper.ts
│   │       ├── postgres.helper.ts
│   │       ├── mongodb.helper.ts
│   │       ├── redis.helper.ts
│   │       └── kafka.helper.ts
│   └── jest-e2e.config.ts
├── docker-compose.e2e.yml
├── .env.e2e
└── package.json

---

Jest の必須設定

// test/jest-e2e.config.ts
const config: Config = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  testMatch: ['**/*.e2e-spec.ts'],
  testTimeout: 25000,
  maxWorkers: 1,           // CRITICAL: Sequential execution
  clearMocks: true,
  forceExit: true,
  detectOpenHandles: true,
};

---

テクノロジー固有のタイムアウト

テクノロジー	待機時間	戦略
Kafka	最大 10～20 秒（ポーリング）	50 ミリ秒間隔のスマートポーリング
PostgreSQL	1 秒未満	直接クエリ
MongoDB	1 秒未満	直接クエリ
Redis	100 ミリ秒未満	インメモリ操作
外部 API	1～5 秒	ネットワーク遅延

---

失敗解決手順

重要：一度に 1 つのテストを修正してください。修正中にテストスイート全体を繰り返し実行しないでください。

E2E テストが失敗した場合：

1. セッションを初期化する（開始時に一度だけ）：

   export E2E_SESSION=$(date +%s)-$$
   

2. 進捗記録ファイルを作成する：失敗したテストをすべて記載した /tmp/e2e-${E2E_SESSION}-failures.md
3. 失敗したテストを 1 つ選ぶ - このテストだけに取り組みます
4. そのテストだけを実行する（テストスイート全体は実行しないでください）：

   npm run test:e2e -- -t "test name" > /tmp/e2e-${E2E_SESSION}-debug.log 2>&1
   tail -50 /tmp/e2e-${E2E_SESSION}-debug.log
   

5. 問題を修正する - エラーを分析し、対象を絞って修正します
6. 修正を検証する - 同じテストを 3～5 回実行します：

   for i in {1..5}; do npm run test:e2e -- -t "test name" > /tmp/e2e-${E2E_SESSION}-run$i.log 2>&1 && echo "Run $i: PASS" || echo "Run $i: FAIL"; done
   

7. 進捗記録ファイルで FIXED とマークします
8. 次の失敗したテストに進む - 手順 3～7 を繰り返します
9. テストスイート全体を実行するのは、個々のテストがすべて合格した後の一度だけです
10. クリーンアップ：rm -f /tmp/e2e-${E2E_SESSION}-*.log /tmp/e2e-${E2E_SESSION}-*.md

理由：テストスイート全体の実行は時間とコンテキストを浪費します。失敗したテストごとに出力が汚染され、デバッグが難しくなります。

---

よくあるパターン

データベースのクリーンアップ（PostgreSQL/MongoDB）

beforeEach(async () => {
  await new Promise(r => setTimeout(r, 500)); // Wait for in-flight
  await repository.clear();  // PostgreSQL
  // OR
  await model.deleteMany({}); // MongoDB
});

Kafka テストのヘルパーパターン

// Use pre-subscription + buffer clearing (NOT fromBeginning: true)
const kafkaHelper = new KafkaTestHelper();
await kafkaHelper.subscribeToTopic(outputTopic, false);
// In beforeEach: kafkaHelper.clearMessages(outputTopic);

Redis のクリーンアップ

beforeEach(async () => {
  await redis.flushdb();
});

外部 API のモック（MSW）

mockServer.use(
  http.post('https://api.external.com/endpoint', () => {
    return HttpResponse.json({ status: 'success' });
  })
);

非同期イベントの検証（Kafka）

// Use smart polling instead of fixed waits
await kafkaHelper.publishEvent(inputTopic, event, event.id);
const messages = await kafkaHelper.waitForMessages(outputTopic, 1, 20000);
expect(messages[0].value).toMatchObject({ id: event.id });

---

デバッグコマンド

すべてのコマンドの出力は、一時ファイルのみにリダイレクトします（コンソールには出力しません）。

# Initialize session (once at start)
export E2E_SESSION=$(date +%s)-$$

# Run specific test (no console output)
npm run test:e2e -- -t "should create user" > /tmp/e2e-${E2E_SESSION}-output.log 2>&1 && tail -50 /tmp/e2e-${E2E_SESSION}-output.log

# Run specific file
npm run test:e2e -- test/e2e/user.e2e-spec.ts > /tmp/e2e-${E2E_SESSION}-output.log 2>&1 && tail -50 /tmp/e2e-${E2E_SESSION}-output.log

# Run full suite
npm run test:e2e > /tmp/e2e-${E2E_SESSION}-output.log 2>&1 && tail -50 /tmp/e2e-${E2E_SESSION}-output.log

# Get failure details from last run
grep -B 2 -A 15 "FAIL\|✕" /tmp/e2e-${E2E_SESSION}-output.log

# Debug with breakpoints (requires console for interactive debugging)
node --inspect-brk node_modules/.bin/jest --config test/jest-e2e.config.ts --runInBand

# View application logs (limited)
tail -100 logs/e2e-test.log
grep -i error logs/e2e-test.log | tail -50

# Cleanup session files
rm -f /tmp/e2e-${E2E_SESSION}-*.log /tmp/e2e-${E2E_SESSION}-*.md

---

避けるべきアンチパターン

1. 複数の WHEN アクション - テストを分割します
2. 条件付きアサーション - 決定的なテストケースを作成します
3. テスト間での状態共有 - beforeEach でクリーンアップします
4. データベースのモック - 実際の接続を使用します
5. クリーンアップの省略 - 前後の両方で必ずクリーンアップします
6. 複数のテストを一度に修正 - 1 つずつ修正します
7. 汎用的なアサーション - 具体的な値をアサートします
8. Kafka での fromBeginning: true - 事前にサブスクライブしてからバッファをクリアします