# テスト方針書

## 概要

本ドキュメントは、Vue.js Core（vuejs/core）v3.5.27 のテスト方針を定義するものである。本プロジェクトはTypeScriptで記述されたモノレポ構成（pnpm workspace）であり、コンパイラ・リアクティブシステム・ランタイム・サーバーサイドレンダリングなど13個のパッケージから構成される。テストフレームワークとしてVitest 3.2.4を採用し、単体テスト・E2Eテスト・型定義テストの3つのプロジェクトに分かれてテストを実行する。GitHub Actionsを用いたCI/CDパイプラインにより、PR・push時に自動テストが実行される。

## テスト戦略

### テストレベル

| レベル | 目的 | 担当 |
| --- | --- | --- |
| 単体テスト（unit） | 各パッケージ内の個別モジュール・関数の正確性を検証する。Node.js環境で実行される compiler-core, compiler-dom, compiler-sfc, compiler-ssr, reactivity, shared, runtime-test, server-renderer が対象 | 開発者 |
| 単体テスト（unit-jsdom） | DOM操作を伴うパッケージ（vue, vue-compat, runtime-dom）のモジュールをjsdom環境で検証する | 開発者 |
| E2Eテスト（e2e） | Puppeteerを用いたブラウザ自動化により、Vue.jsアプリケーション全体の動作をエンドツーエンドで検証する。TodoMVC、トランジション、ハイドレーション、メモリリーク等を対象とする | 開発者 |
| 型定義テスト（dts） | TypeScriptコンパイラ（tsc）を使用し、公開APIの型安全性・型推論の正確性を検証する。defineComponent, ref, watch等の型定義が対象 | 開発者 |

### テスト種別

| 種別 | 概要 | 実施タイミング |
| --- | --- | --- |
| 機能テスト | コンパイラ変換、リアクティブシステム、コンポーネントライフサイクル、VNode処理、SSR出力等の機能的正確性を検証 | PR作成時・push時（CI自動実行） |
| スナップショットテスト | コンパイラ出力コードのスナップショットを記録し、意図しない変更を検知する。compiler-core, compiler-dom, compiler-sfc, compiler-ssr, shared の7ディレクトリに存在 | PR作成時・push時（CI自動実行） |
| メモリリークテスト | memory-leak.spec.ts にてメモリリークの有無を検証 | E2Eテスト実行時 |
| ベンチマークテスト | apiWatch.bench.ts にて性能ベンチマークを実行し、結果をJSON出力して比較可能 | 手動実行（`pnpm bench` / `pnpm bench-compare`） |
| 型安全性テスト | TypeScript宣言ファイルの型チェックにより、公開APIの型互換性を検証 | PR作成時・push時（CI自動実行） |
| クロスプラットフォームテスト | Ubuntu/Windows環境でのコンパイラおよびSSR関連テストの動作検証 | PR作成時・push時（CI自動実行） |
| 静的解析 | ESLint + Prettier によるコードスタイル・品質チェック | PR作成時・push時（CI自動実行） |

## テスト環境

| 環境 | 用途 | 構成 |
| --- | --- | --- |
| Node.js（ネイティブ） | compiler-core, compiler-dom, compiler-sfc, compiler-ssr, reactivity, shared, runtime-test, server-renderer の単体テスト | Node.js 22.14.0+, Vitest 3.2.4, threads poolモード |
| jsdom | vue, vue-compat, runtime-dom の単体テスト。DOM APIをシミュレーション | jsdom 27.4.0, Vitest environment: jsdom |
| Puppeteer（Chromium） | E2Eテスト。実ブラウザ環境でのアプリケーション動作検証 | Puppeteer 24.36.1, headless: true, CI環境では --no-sandbox |
| GitHub Actions（Ubuntu） | CI/CD上での全テスト実行（unit, e2e, dts, lint） | ubuntu-latest, pnpm, Node.js（.node-versionファイル指定） |
| GitHub Actions（Windows） | コンパイラ・SSRのクロスプラットフォーム検証 | windows-latest, compiler + server-renderer のみ |

## テストツール

| ツール | 用途 | バージョン |
| --- | --- | --- |
| Vitest | テストランナー・アサーション・モック | 3.2.4 |
| @vitest/coverage-v8 | コードカバレッジ計測（V8プロバイダー） | 3.2.4 |
| jsdom | ブラウザ環境シミュレーション（DOM API） | 27.4.0 |
| Puppeteer | ブラウザ自動化（E2Eテスト用Chromium制御） | 24.36.1 |
| TypeScript Compiler (tsc) | 型定義テスト（宣言ファイルの型チェック） | プロジェクト指定バージョン |
| ESLint | テストコード品質管理（disabled/focused tests禁止） | プロジェクト指定バージョン |
| @vitest/eslint-plugin | ESLintとVitest連携（テスト品質ルール適用） | 1.6.6 |
| Prettier | コードフォーマットチェック | プロジェクト指定バージョン |

## カバレッジ目標

| 対象 | 目標値 |
| --- | --- |
| 行カバレッジ | 明示的な数値目標は設定されていない（`pnpm run test-coverage` で計測可能） |
| 分岐カバレッジ | 明示的な数値目標は設定されていない |

**カバレッジ計測対象**:
- `packages/*/src/**` 配下の全ソースコード

**カバレッジ除外項目**:
- `packages/vue-compat/**`（Vue 2互換レイヤー）
- `packages/vue/src/dev.ts`（開発モード専用）
- `packages/vue/src/runtime.ts`（ランタイムエントリ）
- `packages/runtime-core/src/profiling.ts`（プロファイリング）
- `packages/runtime-core/src/featureFlags.ts`（フィーチャーフラグ）
- `packages/runtime-core/src/customFormatter.ts`（カスタムフォーマッター）
- `packages/runtime-core/src/hydrationStrategies.ts`（ハイドレーション戦略）
- `packages/runtime-dom/src/components/Transition*`（トランジションコンポーネント）

**カバレッジレポート形式**:
- text（コンソール出力）
- html（ブラウザ閲覧用HTMLレポート）

## テストデータ

テストデータは以下の方法で準備・管理される：

- **インラインテストデータ**: 各テストファイル内にテンプレート文字列やオブジェクトリテラルとして直接定義。コンパイラテストではVueテンプレート文字列、ランタイムテストではコンポーネント定義を使用
- **モックデータファイル**: `packages/vue/__tests__/e2e/commits.mock.ts`（23,553行）にGitHubコミット履歴のモックデータを定義
- **フィクスチャファイル**: `packages/compiler-sfc/__tests__/fixture/` にSCSSインポート等のスタイルフィクスチャを配置
- **HTMLフィクスチャ**: `packages/vue/__tests__/e2e/hydration-strat-*.html`（5ファイル）にハイドレーション戦略テスト用HTMLを配置
- **グローバルスタブ**: `scripts/setup-vitest.ts` にて `MathMLElement` をスタブ化
- **カスタムマッチャー**: `toHaveBeenWarned()`, `toHaveBeenWarnedLast()`, `toHaveBeenWarnedTimes(n)` を `setup-vitest.ts` で定義し、Vue.jsの警告メッセージ検証に使用
- **console.warn のモック**: 全テストで `console.warn` を自動的にスパイし、アサートされなかった警告がある場合はテストを失敗させる仕組み

## 不具合管理

- **課題管理**: GitHubのIssue/Pull Requestを使用
- **テストコード品質**: ESLintルールにより `vitest/no-disabled-tests: error` および `vitest/no-focused-tests: error` を適用し、`skip()` や `only()` がコミットされることを防止
- **未アサート警告の検出**: setup-vitest.ts の afterEach フックにて、テスト中に発生したがアサートされなかった `console.warn` を検出し、テストを強制的に失敗させる
- **スナップショット管理**: `__snapshots__/` ディレクトリでコンパイラ出力の回帰を検知。意図的な変更時はスナップショットの更新が必要

## CI/CD連携

GitHub Actionsによる自動テスト実行が構成されている（`.github/workflows/test.yml`）。

### ワークフロー構成

| ジョブ | 実行環境 | 実行内容 |
| --- | --- | --- |
| `unit-test` | ubuntu-latest | `pnpm run test-unit`（全単体テスト） |
| `unit-test-windows` | windows-latest | `pnpm run test-unit compiler` + `pnpm run test-unit server-renderer`（コンパイラ・SSRのみ） |
| `e2e-test` | ubuntu-latest | `pnpm run test-e2e`（E2Eテスト） + `node scripts/verify-treeshaking.js`（ツリーシェイキング検証） |
| `lint-and-test-dts` | ubuntu-latest | `pnpm run lint` + `pnpm run format-check` + `pnpm run check` + `pnpm run test-dts`（静的解析＋型定義テスト） |

### トリガー条件

- `.github/workflows/ci.yml` から `workflow_call` で呼び出し
- PRおよびpush時に実行
- `release:` で始まるコミットメッセージの場合はスキップ

### E2Eテストの最適化

- Puppeteer（Chromium）のキャッシュを `actions/cache` で管理（キー: `pnpm-lock.yaml` のハッシュ）
- CI環境では E2E テストをシングルスレッドで実行（`singleThread: !!process.env.CI`）

### テスト実行スクリプト一覧

| コマンド | 内容 |
| --- | --- |
| `pnpm test` | 全テスト実行（vitest） |
| `pnpm test-unit` | 単体テストのみ（unit + unit-jsdom プロジェクト） |
| `pnpm test-e2e` | E2Eテスト（Vue global ビルド後に実行） |
| `pnpm test-dts` | 型定義テスト（ビルド後にtsc実行） |
| `pnpm test-dts-only` | 型定義テストのみ（ビルド済み前提） |
| `pnpm test-coverage` | 単体テスト + カバレッジ計測 |
| `pnpm bench` | ベンチマーク実行（JSON出力） |
| `pnpm bench-compare` | ベンチマーク比較（前回結果との差分） |

## 備考

### テストプロジェクト構成（Vitestのprojects機能）

Vitestの `projects` 機能を活用し、テスト実行環境を3つのプロジェクトに分離している：

1. **unit**: Node.js環境での単体テスト。E2EテストおよびDOM依存パッケージ（vue, vue-compat, runtime-dom）を除外
2. **unit-jsdom**: jsdom環境での単体テスト。vue, vue-compat, runtime-dom パッケージが対象
3. **e2e**: jsdom環境 + Puppeteer によるE2Eテスト。`packages/vue/__tests__/e2e/*.spec.ts` が対象

### テストファイル統計

| 項目 | 値 |
| --- | --- |
| 総テストファイル数 | 195個 |
| 総テストコード行数 | 約83,784行 |
| 型定義テストファイル数 | 26個 |
| E2Eテストファイル数 | 13個 |
| スナップショットディレクトリ数 | 7個 |

### パッケージ別テストファイル数

| パッケージ | テストファイル数 | テスト環境 |
| --- | --- | --- |
| compiler-core | 35 | Node.js |
| compiler-dom | 18 | Node.js |
| compiler-sfc | 35 | Node.js |
| compiler-ssr | 16 | Node.js |
| reactivity | 16 | Node.js |
| runtime-core | 45 | Node.js |
| runtime-dom | 16 | jsdom |
| runtime-test | 1 | Node.js |
| server-renderer | 18 | Node.js |
| shared | 7 | Node.js |
| vue | 18（うちE2E 13） | jsdom / Puppeteer |
| vue-compat | 12 | jsdom |
| dts-test | 26 | TypeScript Compiler |

### テストユーティリティ

各パッケージに専用のテストユーティリティが存在する：

- `compiler-core/__tests__/testUtils.ts`: オブジェクトマッチャー生成、コード生成要素作成、フラグテキスト生成
- `compiler-sfc/__tests__/utils.ts`: SFCスクリプトコンパイル、コード検証、位置取得
- `compiler-ssr/__tests__/utils.ts`: SSRコンパイラ用ユーティリティ
- `vue-compat/__tests__/utils.ts`: イベントトリガーユーティリティ
- `vue/__tests__/e2e/e2eUtils.ts`（5,641行）: Puppeteer操作ラッパー、DOM操作ヘルパー、ポーリングベースのアサーション

### テスト時のグローバル定義

テスト実行時に以下のグローバル定数が定義される（vitest.config.ts の define 設定）：

| 定数 | 値 | 用途 |
| --- | --- | --- |
| `__DEV__` | true | 開発モードフラグ |
| `__TEST__` | true | テスト実行中フラグ |
| `__VERSION__` | "test" | バージョン文字列 |
| `__BROWSER__` | false | ブラウザ環境フラグ |
| `__GLOBAL__` | false | グローバルビルドフラグ |
| `__ESM_BUNDLER__` | true | ESMバンドラーターゲット |
| `__ESM_BROWSER__` | false | ブラウザESMフラグ |
| `__CJS__` | true | CommonJSフラグ |
| `__SSR__` | true | SSR対応フラグ |
| `__FEATURE_OPTIONS_API__` | true | Options API有効化 |
| `__FEATURE_SUSPENSE__` | true | Suspense有効化 |
| `__COMPAT__` | true | 互換性モード有効化 |

### テスト命名規則

| パターン | 用途 |
| --- | --- |
| `*.spec.ts` | 単体テスト・E2Eテスト |
| `*.test-d.ts` / `*.test-d.tsx` | 型定義テスト |
| `*.bench.ts` | ベンチマークテスト |
| `utils.ts` / `testUtils.ts` | テストユーティリティ |
| `*.mock.ts` | モックデータ |
