# テスト方針書

## 概要

本ドキュメントは、JestリポジトリにおけるテストのテストスタテジーおよびCI/CDパイプラインにおけるテスト実行方針を定義したものである。Jestは55以上のパッケージを含むTypeScriptモノレポであり、Lerna-liteとYarn Workspacesで管理されている。本リポジトリでは、単体テストと結合テスト（E2Eテスト）の2層構造でテストを実施する。

## テスト戦略

### テストレベル

| レベル | 目的 | 担当 |
| --- | --- | --- |
| 単体テスト | 各パッケージの個別機能の正確性を検証する。モジュール単位での動作確認を行う | 開発者 |
| 結合テスト（E2E） | Jest CLIを実際に実行し、複数パッケージの連携動作、出力結果（status、stdout、stderr）を検証する | 開発者 |
| TypeScript互換性テスト | TypeScript 5.4以降との互換性、型定義の正確性を検証する | CI/CD自動実行 |
| リークテスト | メモリリークの検出を行う。jest-mock、jest-diff、pretty-formatパッケージが対象 | CI/CD自動実行 |

### テスト種別

| 種別 | 概要 | 実施タイミング |
| --- | --- | --- |
| 機能テスト | Jest各パッケージの機能が仕様通りに動作することを確認する | プルリクエスト時、main ブランチへのpush時 |
| 互換性テスト | 複数のNode.jsバージョン（18.x, 20.x, 22.x, 24.x）での動作確認 | CI/CDパイプライン実行時 |
| クロスプラットフォームテスト | Ubuntu、macOS、Windowsでの動作確認 | CI/CDパイプライン実行時 |
| Jasmine互換テスト | jest-jasmine2ランナーでの後方互換性確認 | CI/CDパイプライン実行時 |
| 静的解析 | ESLint、Prettier、TypeScript型チェックによるコード品質確認 | プルリクエスト時 |

## テスト環境

| 環境 | 用途 | 構成 |
| --- | --- | --- |
| ローカル開発環境 | 開発時のテスト実行 | Node.js ^18.14.0 / ^20.0.0 / ^22.0.0 / >=24.0.0、Yarn 4.12.0 |
| GitHub Actions (Ubuntu) | CI/CDでのメインテスト実行 | ubuntu-latest、4シャードで並列実行 |
| GitHub Actions (macOS) | クロスプラットフォーム検証 | macos-latest、3シャードで並列実行 |
| GitHub Actions (Windows) | クロスプラットフォーム検証 | windows-latest、4シャードで並列実行 |

## テストツール

| ツール | 用途 | バージョン |
| --- | --- | --- |
| Jest | テストフレームワーク（セルフホスティング） | workspace:* |
| jest-circus | デフォルトのテストランナー | workspace:* |
| jest-jasmine2 | レガシーテストランナー（互換性テスト用） | workspace:* |
| babel-jest | TypeScript/JSXトランスフォーマー | workspace:* |
| jest-junit | JUnit形式のテストレポート出力 | ^16.0.0 |
| jest-silent-reporter | CI向けの簡易レポーター | ^0.6.0 |
| jest-watch-typeahead | ウォッチモードでのテスト絞り込み支援 | ^3.0.1 |
| TSTyche | TypeScript型テスト | ^5.0.0 |
| ESLint | 静的コード解析 | ^9.28.0 |
| Prettier | コードフォーマット | ^3.0.3 |
| Codecov | カバレッジレポート収集・可視化 | codecov-action v5.4.2 |

## カバレッジ目標

| 対象 | 目標値 |
| --- | --- |
| 行カバレッジ | 明示的な目標値は設定されていないが、Codecovで継続的に計測 |
| カバレッジ収集対象 | packages/*内の.js/.tsファイル（build、vendor、__tests__等は除外） |

**カバレッジ設定詳細:**

- 収集対象パターン: `**/packages/*/**/*.js`, `**/packages/*/**/*.ts`
- 除外パターン:
  - `**/bin/**`
  - `**/cli/**`
  - `**/__benchmarks__/**`
  - `**/__mocks__/**`
  - `**/__tests__/**`
  - `**/__typetests__/**`
  - `**/build/**`
  - `**/vendor/**`
  - `e2e/**`

## テストデータ

### 単体テスト

- 各パッケージの`__tests__`ディレクトリ内にテストファイルを配置
- `__fixtures__`ディレクトリにテスト用のフィクスチャデータを配置
- `__mocks__`ディレクトリにモックモジュールを配置

### E2Eテスト

- `e2e/`ディレクトリ内に190以上のテストシナリオを配置
- 各サブディレクトリがテストフィクスチャとして機能
- E2Eテストではモックを使用せず、実際のファイルシステムを使用（ESLintで強制）
- テストは`e2e/__tests__/`ディレクトリ内の`.test.ts`ファイルで実行

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

- `e2e/Utils.ts` - E2Eテスト用の共通ユーティリティ関数
- `packages/test-utils` - テスト用の共通ユーティリティパッケージ

## 不具合管理

### 報告方法

- GitHub Issuesを使用して公開バグを管理
- セキュリティバグは`SECURITY.md`に従った非公開プロセスで報告

### 不具合修正フロー

1. GitHub Issueで問題を報告または確認
2. フォークしてブランチを作成
3. テストを追加して不具合を再現
4. 修正を実装
5. `yarn test`で全テストがパスすることを確認
6. `CHANGELOG.md`にエントリを追加
7. プルリクエストを作成

### テスト失敗時の対応

- CI/CDでは最大3回のリトライを実施（タイムアウト: 10分）
- fail-fast: falseで設定されており、1つのシャードの失敗が他に影響しない

## CI/CD連携

### GitHub Actionsワークフロー構成

#### メインワークフロー（nodejs.yml）

トリガー:
- `main`ブランチへのpush
- プルリクエスト
- マージグループ

並行実行制御:
- 同一ブランチの古いワークフローは自動キャンセル

#### ジョブ構成

1. **prepare-yarn-cache** (Ubuntu/macOS/Windows)
   - Yarnキャッシュの準備

2. **ts-compatibility**
   - TypeScript互換性テスト
   - TypeScript 5.4以降との互換性検証
   - TSTycheによる型テスト
   - ESLintの型情報付き実行

3. **static-checks**
   - ESLint実行
   - Prettier形式チェック
   - TypeScript型チェック（examples、tests）
   - Yarn PnP互換性検証
   - Changelogリンク検証
   - 著作権ヘッダー検証
   - Yarn constraints検証
   - 重複依存関係チェック

4. **test-ubuntu/macos/windows**
   - Node.js 18.x, 20.x, 22.x, 24.xでのテスト実行
   - シャーディングによる並列実行（Ubuntu/Windows: 4シャード、macOS: 3シャード）
   - jest-jasmine2ランナーでの互換性テスト

5. **test-leak**
   - メモリリーク検出テスト
   - 対象: jest-mock、jest-diff、pretty-format

6. **test-coverage**
   - 4シャードでカバレッジ収集
   - Codecovへのレポートアップロード

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

```bash
# 全テスト実行
yarn test

# Jest単体実行
yarn jest

# CI用テスト実行（シャーディング対応）
yarn test-ci-partial:parallel --max-workers <N> --shard=<M>/<N>

# カバレッジ付きテスト
yarn jest-coverage

# jest-jasmine2ランナーでのテスト
yarn jest-jasmine

# リークテスト
yarn test-leak

# TypeScript統合テスト
yarn test-ts

# 型テスト
yarn test-types
```

### テストタイムアウト設定

- デフォルトタイムアウト: 70,000ms（70秒）
- CI実行時のタイムアウト: 10分（リトライ含む）

## 備考

### ビルド要件

テストはビルド済みの出力（`packages/*/build/`）に対して実行されるため、テスト実行前に必ずビルドが必要:

```bash
yarn install
yarn build:js  # 通常の開発には十分
# または
yarn build     # 型定義作業時はフルビルド
```

### 環境変数

| 変数名 | 説明 |
| --- | --- |
| `JEST_JASMINE=1` | jest-jasmine2ランナーを使用 |
| `GLOBALS_CLEANUP=off` | グローバルクリーンアップを無効化 |

### 外部依存関係

- 一部のE2Eテストにはmercurial（`hg`）のインストールが必要
- macOSでは`brew install hg`でインストール可能

### テストファイル命名規則

- 単体テスト: `*.test.ts`または`*.test.js`
- E2Eテスト: `e2e/__tests__/*.test.ts`
- 型テスト: `__typetests__/*.ts`（TSTycheで実行）

### スナップショットテスト

- `jest-serializer-ansi-escapes`を使用してANSIエスケープシーケンスをシリアライズ
- `snapshotFormat.printBasicPrototype: true`でプロトタイプを出力
