# テスト方針書

## 概要

本ドキュメントは、Tailwind CSS v4 プロジェクトにおけるテスト方針を定義する。本プロジェクトは JavaScript/TypeScript と Rust のハイブリッド構成のモノレポであり、CSS ユーティリティフレームワークとしてコア変換エンジン、CLI、PostCSS プラグイン、Vite プラグイン、Webpack プラグイン等の複数パッケージを含む。テストは単体テスト・統合テスト・E2E テストの 3 層構成で実施し、クロスプラットフォーム（Windows / macOS / Linux）での品質を保証する。

## テスト戦略

### テストレベル

| レベル | 目的 | 担当 |
| --- | --- | --- |
| 単体テスト | 各パッケージ内の関数・モジュール単位の動作検証。CSS コンパイル、ユーティリティ生成、IntelliSense 出力等の正確性を検証 | 各パッケージ開発者 |
| 統合テスト | CLI・PostCSS・Vite・Webpack 等のバンドラー/ツールチェーンとの統合動作を検証。ファイル監視、増分ビルド、設定ファイル解釈を含む | 統合テスト担当 |
| E2E テスト（UI テスト） | ブラウザ上での実際の CSS レンダリング結果を Playwright で検証。グラデーション、ホバー状態、動的スタイル変更等の視覚的正確性を検証 | E2E テスト担当 |

### テスト種別

| 種別 | 概要 | 実施タイミング |
| --- | --- | --- |
| 機能テスト | CSS ユーティリティクラスの生成、テーマ解決、プラグイン処理等のコア機能テスト | 各コミット時（CI）、ローカル開発時（TDD） |
| スナップショットテスト | CSS 出力結果、IntelliSense 出力、ユーティリティ生成結果をスナップショットで回帰検証 | 各コミット時（CI）、ローカル開発時 |
| クロスプラットフォームテスト | Windows / macOS / Linux での一貫した動作を検証（パス区切り文字、改行コード、浮動小数点精度の差異吸収） | CI 上でのマトリクス実行 |
| ブラウザ横断テスト | Chromium / WebKit / Firefox での CSS レンダリング検証 | CI 上での Playwright 実行 |
| Rust ユニットテスト | Oxide スキャナー、gitignore パターンマッチング等の Rust コア処理テスト | 各コミット時（`cargo test`） |
| ベンチマークテスト | パフォーマンス計測（CSS コンパイル速度等） | 手動実行（`pnpm run bench`） |

## テスト環境

| 環境 | 用途 | 構成 |
| --- | --- | --- |
| ローカル開発環境 | 日常の開発・TDD | Node.js 24、pnpm ワークスペース、Rust ツールチェーン |
| CI 環境（GitHub Actions） | 自動テスト・品質ゲート | Ubuntu Linux / Windows / macOS マトリクス、Node.js 24 |
| Playwright テスト環境 | ブラウザ E2E テスト | Chromium / WebKit / Firefox（CI では依存関係付きインストール） |

## テストツール

| ツール | 用途 | バージョン |
| --- | --- | --- |
| Vitest | JavaScript/TypeScript ユニット・統合テストフレームワーク | ^4.0.18 |
| Playwright | ブラウザ E2E テストフレームワーク（マルチブラウザ対応） | ^1.58.0 |
| Cargo Test | Rust コードのテストランナー | Rust ツールチェーン同梱 |
| pretty_assertions | Rust テスト用の見やすいアサーション出力 | 1.4.1 |
| tempfile | Rust テスト用の一時ファイル管理 | 3.13.0 |
| Prettier | テストコードの自動整形 | devDependencies に含まれる |
| pnpm | モノレポパッケージマネージャー・テスト実行統合 | ワークスペース管理 |
| Turbo | モノレポビルド・テストオーケストレーション | devDependencies に含まれる |

## カバレッジ目標

| 対象 | 目標値 |
| --- | --- |
| 行カバレッジ | 明示的な数値目標は未設定 |
| 分岐カバレッジ | 明示的な数値目標は未設定 |

**補足**: 本プロジェクトでは Vitest のカバレッジ機能（`@vitest/coverage-*`）は設定されていない。代わりに、以下の方針でテスト品質を確保している:

- コアパッケージ（`tailwindcss`）で 38 個のテストファイル・大量のスナップショットによる高密度な出力検証
- 統合テスト 38 ファイルによる各ツールチェーン連携の網羅
- E2E テストによるブラウザレンダリングの最終検証
- 3 OS × マルチブラウザの CI マトリクスによる環境差異の検出

## テストデータ

### テストデータ準備方針

- **インラインテストデータ**: 単体テストでは CSS 入力文字列と期待される候補クラスをテストコード内に直接記述する。`compileCss(css, candidates)` ヘルパーを通じてコンパイル結果を検証する
- **スナップショット**: CSS 出力結果を `__snapshots__/` ディレクトリにスナップショットとして保存し、回帰検証に使用する。Color 関数の浮動小数点精度は `custom-serializer.ts` で正規化される
- **テスト用ファイルシステム**: 統合テストでは `TestConfig.fs` オブジェクトで仮想ファイルシステムを定義し、一時ディレクトリに展開する。テスト完了後は自動クリーンアップされる（`debug: true` 時を除く）
- **Rust テストデータ**: `tempfile` クレートによる一時ファイル・ディレクトリを使用

### OS 差異の吸収

- Windows の `\r\n` 改行を正規化して比較
- Windows のパス区切り文字 `\` を `/` に変換（`normalizeWindowsSeperators`）
- Color 関数（`oklab()` / `oklch()` / `lab()` / `lch()`）の浮動小数点精度を OS 間で統一

## 不具合管理

### 不具合管理方法

- **課題管理**: GitHub Issues を使用して不具合を追跡する
- **CI 失敗通知**: CI テスト失敗時は Discord へ自動通知が送信される（`ci.yml` 内の通知設定）
- **リトライ戦略**: CI 環境では不安定なテスト（flaky tests）に対応するため、テスト実行を最大 2 回リトライする
  - Playwright: `retries: process.env.CI ? 2 : 0`
  - 統合テスト: `retry: process.env.CI ? 2 : 0`
- **テスト条件スキップ**: 環境依存のテストは条件付きスキップを行い、`hideSkippedTests: true` でノイズを低減する

## CI/CD 連携

### メインテストパイプライン（`ci.yml`）

**トリガー**: `main` ブランチへの push および Pull Request

**実行フロー**:
1. 依存関係インストール（pnpm install、Cargo キャッシュ復元）
2. プロジェクトビルド（`pnpm run build`）
3. リントチェック（`pnpm run lint`、Linux のみ）
4. ユニットテスト実行（`pnpm run test` = `cargo test && vitest run`）
5. Playwright ブラウザインストール（`npx playwright install --with-deps`）
6. E2E テスト実行（`pnpm run test:ui`）

**マトリクス構成**:
- OS: `ubuntu-latest`, `windows-latest`, `macos-14`
- Node.js: v24

**並行実行制御**: 同一 ref に対する新しいワークフロー実行時、前回の実行を自動キャンセルする

### 統合テストパイプライン（`integration-tests.yml`）

**トリガー**: `main` ブランチへの push および Pull Request

**マトリクス構成**:
- OS: `ubuntu-latest`, `windows-latest`, `macos-14`
- Integration: `upgrade`, `vite`, `cli`, `postcss`, `oxide`, `webpack`

**実行コマンド**: `pnpm run test:integrations ./integrations/${{ matrix.integration }}`

**タイムアウト**: 30 分

### テスト実行コマンド一覧

| コマンド | 用途 |
| --- | --- |
| `pnpm run test` | Cargo テスト + Vitest ユニットテスト一括実行 |
| `pnpm run tdd` | Vitest ファイル監視モード（TDD 用） |
| `pnpm run test:integrations` | 統合テスト実行（integrations ディレクトリ） |
| `pnpm run test:ui` | Playwright E2E テスト実行 |
| `pnpm run bench` | ベンチマークテスト実行 |
| `cargo test` | Rust ユニットテスト実行 |

## 備考

### モノレポテスト構成

本プロジェクトは pnpm ワークスペース + Turbo によるモノレポ構成を採用しており、ルートの `vitest.config.ts` で各パッケージのテストプロジェクトを統合管理している。統合テストは `integrations/` ディレクトリで独立した Vitest プロジェクトとして管理され、`*.spec.ts`（Playwright）と `*.test.ts`（Vitest）の拡張子で種別を区別している。

### テストファイル規模

| カテゴリ | ファイル数 | 概算行数 |
| --- | --- | --- |
| 単体テスト（TypeScript） | 約 113 ファイル | 約 50,000 行 |
| 統合テスト | 約 38 ファイル | 約 16,050 行 |
| E2E テスト（Playwright） | 2 ファイル | - |
| Rust テスト | 3 ファイル | - |

### ハイブリッド言語テスト

JavaScript/TypeScript テスト（Vitest）と Rust テスト（Cargo Test）が `pnpm run test` コマンドで一括実行される。Rust の Oxide エンジンは N-API を通じて Node.js から呼び出されるため、統合テストでは JavaScript 側から Rust バイナリの動作も間接的に検証される。

### デバッグ支援

統合テストでは `{ debug: true }` オプションにより、テスト用ファイルシステムを `.debug` ディレクトリに保持し、CLI コマンド実行ログを詳細出力できる。これにより CI 上での問題調査を効率化している。
