# テスト方針書

## 概要

本ドキュメントは、webpack（v5.105.3）プロジェクトにおけるテスト方針を定義する。webpackはJavaScriptモジュールバンドラーであり、大規模かつ多層的なテスト戦略を採用している。テストフレームワークとしてJestを使用し、単体テスト・結合テスト（configCases、statsCases等）・仕様準拠テスト（test262）・性能ベンチマークまで幅広いテストレベルをカバーしている。

## テスト戦略

### テストレベル

| レベル | 目的 | 担当 |
| --- | --- | --- |
| 単体テスト（unittest） | 個別モジュール・ユーティリティ関数の正確性検証。`*.unittest.js`（49ファイル）として定義 | 開発者 |
| 基本テスト（basictest） | webpack設定ケースの基本動作検証。`*.basictest.js`（5ファイル）として定義。ConfigTestCases、ConfigCacheTestCases等を含む | 開発者 |
| 結合テスト（test） | Compiler、HMR、Watch、Stats等のコンポーネント間連携テスト。`*.test.js`（38ファイル）として定義 | 開発者 |
| 長時間テスト（longtest） | 大規模ビルド・ウォッチモード等の長時間実行テスト。`*.longtest.js`（9ファイル）として定義 | CI |
| 仕様準拠テスト（spectest） | TC39 test262仕様への準拠検証。`*.spectest.js`（1ファイル）として定義 | CI |
| ベンチマーク | ビルド性能の計測・回帰検出。`BenchmarkTestCases.benchmark.mjs`として定義 | CI（CodSpeed） |

### テスト種別

| 種別 | 概要 | 実施タイミング |
| --- | --- | --- |
| 機能テスト | webpack各機能（ローダー、プラグイン、最適化、コード分割等）の動作検証。test/cases/（25カテゴリ）、test/configCases/（91カテゴリ）、test/statsCases/（128ケース）として管理 | PR作成時・push時 |
| HMRテスト | Hot Module Replacement機能のテスト。test/hotCases/（30カテゴリ）をNode/Web/WebWorker/AsyncNode環境で実行 | PR作成時・push時 |
| Watchテスト | ファイル変更監視・再ビルド機能のテスト。test/watchCases/（16カテゴリ）として管理 | PR作成時・push時 |
| 性能テスト | ビルド速度・メモリ使用量の計測。CodSpeedプラットフォームでシミュレーション・メモリモードを実行 | PR作成時・push時 |
| 型検査テスト | TypeScript型定義の正確性検証。tsconfig.types.test.json、tsconfig.module.test.jsonで検証 | lint実行時 |
| メモリリミットテスト | メモリ制限下でのビルド動作検証。test/memoryLimitCases/として管理 | PR作成時・push時 |

## テスト環境

| 環境 | 用途 | 構成 |
| --- | --- | --- |
| ローカル開発環境 | 開発中のテスト実行 | Node.js（LTS推奨）、yarn、Jest |
| GitHub Actions - lint | リント・型検査 | ubuntu-latest、Node.js LTS |
| GitHub Actions - basic | 基本テスト実行 | ubuntu-latest、Node.js LTS |
| GitHub Actions - unit | 単体テスト実行+カバレッジ | ubuntu-latest、Node.js LTS |
| GitHub Actions - integration | 結合テスト実行（マルチプラットフォーム・マルチバージョン） | ubuntu/windows/macos-latest × Node.js 10.x/12.x/14.x/16.x/18.x/20.x/22.x/24.x/25.x |
| GitHub Actions - test262 | TC39仕様準拠テスト | ubuntu-latest、Node.js latest |
| GitHub Actions - benchmarks | 性能ベンチマーク | ubuntu-latest、Node.js LTS、CodSpeed |

## テストツール

| ツール | 用途 | バージョン |
| --- | --- | --- |
| Jest | テストフレームワーク・テストランナー | ^30.2.0 |
| jest-circus | テストランナー（Jestデフォルト） | ^30.2.0 |
| jest-cli | CLIインターフェース | ^30.2.0 |
| jest-environment-node | Node.jsテスト環境（カスタム拡張あり） | ^30.2.0 |
| jest-diff | 差分比較 | ^30.2.0 |
| jest-junit | JUnit形式レポート出力 | ^16.0.0 |
| nyc / istanbul | コードカバレッジ計測 | nyc ^18.0.0 |
| Codecov | カバレッジレポート集約・可視化 | GitHub Actions連携 |
| CodSpeed | 性能ベンチマーク計測プラットフォーム | GitHub Actions連携 |
| tinybench | ベンチマーク実行ライブラリ | ^6.0.0 |
| memfs | インメモリファイルシステム（テスト用） | ^4.51.1 |
| ESLint | 静的解析 | ^9.39.2 |
| TypeScript | 型検査 | ^5.9.3 |
| Prettier | コードフォーマット検証 | ^3.7.4 |
| cspell | スペルチェック | ^9.4.0 |
| husky + lint-staged | pre-commitフック | husky ^9.0.11 |

## カバレッジ目標

| 対象 | 目標値 |
| --- | --- |
| 行カバレッジ | 明示的な数値目標は設定されていないが、Codecovによる継続的な追跡を実施 |
| 分岐カバレッジ | 明示的な数値目標は設定されていないが、Codecovによる継続的な追跡を実施 |
| 型カバレッジ | TypeScript型定義のカバレッジをlcovレポートとして計測・PRにコメントで報告 |

カバレッジ計測方針：
- 単体テスト（unit）、結合テスト（integration:a / integration:b）、仕様準拠テスト（test262）ごとにフラグ付きでCodecovに送信
- カバレッジ対象外：ランタイムコード（`\.runtime\.js$`）、テストコード、スキーマ、サンプル、node_modules
- カバレッジレポート形式：JSON形式でローカル出力後、nycでlcov/textレポートに変換

## テストデータ

- **テストケースディレクトリ方式**: 各テストケースは独立したディレクトリとして管理される（test/cases/、test/configCases/、test/hotCases/、test/watchCases/、test/statsCases/）
- **fixtures**: test/fixtures/ にビルド依存関係・ブラウザリスト・ウォッチ用のテストデータを配置
- **node_modules模擬**: 各テストケースディレクトリ内にローカルなnode_modulesを配置し、パッケージ解決のテストを実施
- **期待値ファイル**: テストケースごとにindex.js（テスト本体）、webpack.config.js（設定）、test.filter.js（フィルタ条件）等で構成
- **スナップショット**: test/__snapshots/ にJestスナップショットテストの期待値を保存
- **テンプレート方式**: ConfigTestCases.template.js、HotTestCases.template.js、WatchTestCases.template.jsにより、テストケースディレクトリから自動的にテストスイートを生成

## 不具合管理

- **Issue管理**: GitHub Issuesで不具合を管理（https://github.com/webpack/webpack/issues）
- **回帰テスト**: 修正された不具合に対応するテストケースをissue番号付きで追加（例: `issue-7400`、`issue-12570`、`issue-10475`等のディレクトリ名）
- **テスト失敗時のリトライ**: CI上で結合テスト失敗時に`-f`（失敗テストのみ再実行）オプションで自動リトライを実施

## CI/CD連携

- **プラットフォーム**: GitHub Actions
- **トリガー**: mainブランチへのpush、mainブランチへのPull Request
- **同時実行制御**: ワークフロー単位でconcurrency制御（同一refの重複実行をキャンセル）
- **パイプライン構成**:
  1. **lint**: ESLint、Prettier、cspell、TypeScript型検査を実行
  2. **basic**: 基本テストを実行（他テストの前提条件）
  3. **unit**: 単体テスト+カバレッジ計測（Codecov送信）
  4. **test262**: TC39仕様準拠テスト（basicの完了後に実行）
  5. **integration**: マルチプラットフォーム×マルチNode.jsバージョンのマトリクステスト（basicの完了後に実行、パートa/bに分割）
  6. **benchmarks**: CodSpeedによるシミュレーション+メモリベンチマーク（4シャードに分割）
  7. **types-coverage**: TypeScript型カバレッジ計測（PRにコメントで報告）
  8. **validate-legacy-node**: Node.js 10.xでのインストール互換性確認
- **キャッシュ**: Jest結果、ESLint結果、Prettier結果、cspell結果をGitHub Actionsキャッシュで高速化
- **レガシーNode.js対応**: Node.js 10.x〜16.xでは古いバージョンのJest（^27.5.0）等にダウングレードして実行
- **pre-commitフック**: husky + lint-stagedによるコミット前のESLint・Prettier・cspell自動実行

## 備考

- **カスタムテスト環境**: `test/patch-node-env.js` でjest-environment-nodeを拡張したカスタム環境を使用
- **カスタムマッチャー**: `test/setupTestFramework.js` で`toBeTypeOf`、`toEndWith`のカスタムJestマッチャーを定義
- **テストヘルパー**: test/helpers/ に50以上のヘルパーモジュールを配置（機能サポート判定、モック、キャプチャ等）
- **テストランナー**: test/runner/ にカスタムテストランナーを実装し、configCasesやhotCasesのテンプレートベースのテスト実行を管理
- **メモリ管理**: テスト実行時に`--expose-gc --max-old-space-size=4096`でメモリ管理を最適化
- **VM modules**: `--experimental-vm-modules`フラグによりESMモジュールのテストをサポート
- **テストタイムアウト**: Jest設定で30,000ms（30秒）のデフォルトタイムアウトを設定
- **Deno対応**: `test:basic:deno`スクリプトによるDeno環境でのテスト実行もサポート
- **依存関係のmainブランチテスト**: CI上でenhanced-resolve、loader-runner、webpack-sources、watchpack、tapableのmainブランチでもテストを実行し、上流の破壊的変更を早期検出
