# 機能設計書 27-jest-environment-jsdom

## 概要

本ドキュメントは、Jestのjsdomテストテスト環境（jest-environment-jsdom）の機能設計を記述する。このパッケージは、jsdomを使用したブラウザシミュレーション環境でテストを実行するためのJestEnvironment実装を提供する。

### 本機能の処理概要

jest-environment-jsdomは、jsdomライブラリを使用してブラウザ環境をシミュレートするJestテスト環境を提供するパッケージである。DOM API、window、document等のブラウザ環境固有のオブジェクトを使用したテストが可能になる。

**業務上の目的・背景**：フロントエンドアプリケーションやReactコンポーネントのテストでは、DOM操作やブラウザAPIの使用が必要となる。jest-environment-jsdomは、実際のブラウザを起動することなく、Node.js上でブラウザ環境をシミュレートし、高速なテスト実行を可能にする。

**機能の利用シーン**：
- Reactコンポーネントのテスト
- DOM操作を含むコードのテスト
- ブラウザAPIを使用するコードのテスト
- フロントエンドライブラリのテスト

**主要な処理内容**：
1. jsdomインスタンスの作成とWindow取得
2. VirtualConsoleの設定（コンソール出力転送）
3. グローバルエラーイベントリスナーの設定
4. フェイクタイマー（Legacy/Modern）の初期化
5. ModuleMockerの初期化

**関連システム・外部連携**：
- jsdom: ブラウザ環境シミュレーション
- @jest/environment-jsdom-abstract: 抽象基底クラス
- @jest/fake-timers: フェイクタイマー
- jest-mock: モック機能

**権限による制御**：この機能に権限による制御は存在しない。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 22 | Configurationページ | 補助機能 | jsdom環境設定オプションの説明 |

## 機能種別

テスト実行環境

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| config | JestEnvironmentConfig | Yes | 環境設定（projectConfig, globalConfig） | - |
| context | EnvironmentContext | Yes | 環境コンテキスト（console, testPath） | - |

### testEnvironmentOptions

| オプション名 | 型 | デフォルト | 説明 |
|-------------|-----|----------|------|
| html | string | `<!DOCTYPE html>` | 初期HTML |
| userAgent | string | - | カスタムユーザーエージェント |
| customExportConditions | Array<string> | ['browser'] | エクスポート条件 |
| その他 | - | - | jsdom ConstructorOptionsに準拠 |

### 入力データソース

- jest-runtimeからのテスト実行リクエスト
- Jest設定ファイル

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| global | Win (Window) | jsdomのWindowオブジェクト |
| dom | JSDOM | jsdomインスタンス |
| fakeTimers | LegacyFakeTimers | レガシーフェイクタイマー |
| fakeTimersModern | ModernFakeTimers | モダンフェイクタイマー |
| moduleMocker | ModuleMocker | モジュールモッカー |

### 出力先

- テスト実行環境

## 処理フロー

### 処理シーケンス

```
1. コンストラクタ呼び出し
   └─ jsdomモジュール受け取り
   └─ VirtualConsoleの設定
   └─ JSDOMインスタンスの作成

2. グローバル設定
   └─ Windowオブジェクトの取得
   └─ Error.stackTraceLimitを100に設定
   └─ installCommonGlobals呼び出し
   └─ Bufferの設定

3. エラーハンドリング設定
   └─ errorEventListenerの設定
   └─ addEventListener/removeEventListenerのラップ

4. モック/タイマーの初期化
   └─ ModuleMockerの作成
   └─ LegacyFakeTimersの作成
   └─ ModernFakeTimersの作成

5. teardown()呼び出し
   └─ fakeTimersのdispose
   └─ errorEventListenerの削除
   └─ window.close()
```

### フローチャート

```mermaid
flowchart TD
    A[コンストラクタ] --> B[VirtualConsole設定]
    B --> C[JSDOM作成]
    C --> D[Window取得]
    D --> E[グローバル設定]
    E --> F[エラーハンドリング設定]
    F --> G[ModuleMocker初期化]
    G --> H[FakeTimers初期化]
    H --> I[テスト実行]
    I --> J[teardown]
    J --> K[リソース解放]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-27-01 | デフォルトURL | jsdomのデフォルトURLは'http://localhost/' | 常時 |
| BR-27-02 | runScripts | runScriptsは'dangerously'に設定 | 常時 |
| BR-27-03 | pretendToBeVisual | pretendToBeVisualはtrue | 常時 |
| BR-27-04 | エラー転送 | ユーザーがerrorリスナーを設定していない場合、uncaughtExceptionとして転送 | エラー発生時 |
| BR-27-05 | Error.stackTraceLimit | エラースタックトレース上限を100に設定 | 初期化時 |

### 計算ロジック

計算処理は存在しない。

## データベース操作仕様

### 操作別データベース影響一覧

データベース操作は存在しない。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | TypeError | VirtualConsoleのforwardTo/sendToメソッドがない場合 | jsdomバージョンを確認 |
| - | Error | JSDOMがWindowオブジェクトを返さない場合 | jsdomの設定を確認 |
| - | Error | customExportConditionsが文字列配列でない場合 | 文字列配列を指定 |

### リトライ仕様

リトライ処理は存在しない。

## トランザクション仕様

トランザクション処理は存在しない。

## パフォーマンス要件

- jsdomインスタンス作成は各テストファイルごとに行われる
- window.close()で適切にリソースを解放

## セキュリティ考慮事項

- runScripts: 'dangerously'が設定されているため、信頼できないコードは実行しないこと
- テスト用途のみを想定

## 備考

- jest-environment-jsdomはjest-environment-nodeの代替として使用
- canvasパッケージはオプショナル依存（Canvas APIを使用する場合に必要）

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | index.ts | `packages/jest-environment-jsdom/src/index.ts` | JSDOMEnvironmentクラス |

**読解のコツ**: jest-environment-jsdomは非常にシンプルで、@jest/environment-jsdom-abstractを継承してjsdomモジュールを渡すだけ。

**主要処理フロー**:
- **15-18行目**: JSDOMEnvironmentクラス定義とコンストラクタ
- **17行目**: 親クラスにjsdomモジュールを渡す
- **21行目**: TestEnvironmentとしてもエクスポート

#### Step 2: 基底クラスを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | index.ts | `packages/jest-environment-jsdom-abstract/src/index.ts` | BaseJSDOMEnvironmentクラス |

**主要処理フロー**:
- **33-41行目**: クラス定義とプロパティ
- **43-172行目**: コンストラクタ
  - **50行目**: jsdomモジュールから必要なクラスを取得
  - **52-71行目**: VirtualConsoleの設定
  - **77-94行目**: JSDOMインスタンスの作成
  - **106行目**: Error.stackTraceLimitを100に設定
  - **113-140行目**: エラーイベントリスナーの設定
  - **156-171行目**: FakeTimers初期化
- **175行目**: setup() - 空実装
- **177-196行目**: teardown() - リソース解放
- **198-200行目**: exportConditions() - エクスポート条件取得
- **202-207行目**: getVmContext() - VMコンテキスト取得

### プログラム呼び出し階層図

```
@jest/runtime
    │
    └─ jest-environment-jsdom
           │
           └─ JSDOMEnvironment (extends BaseJSDOMEnvironment)
                  │
                  └─ @jest/environment-jsdom-abstract
                         │
                         ├─ constructor()
                         │      ├─ VirtualConsole設定
                         │      ├─ JSDOM作成
                         │      ├─ installCommonGlobals()
                         │      ├─ エラーリスナー設定
                         │      ├─ ModuleMocker()
                         │      ├─ LegacyFakeTimers()
                         │      └─ ModernFakeTimers()
                         │
                         ├─ setup()
                         ├─ teardown()
                         ├─ getVmContext()
                         └─ exportConditions()
```

### データフロー図

```
[入力]                         [処理]                              [出力]

JestEnvironmentConfig ─────▶ JSDOMEnvironment ─────▶ ブラウザ環境シミュレーション
     │                              │
     │                              ├─▶ jsdom.JSDOM
     │                              │      ├─ window
     │                              │      ├─ document
     │                              │      └─ navigator
     │                              │
     │                              ├─▶ ModuleMocker
     │                              │
     │                              └─▶ FakeTimers (Legacy/Modern)
     │
testEnvironmentOptions
     ├─ html
     ├─ userAgent
     └─ customExportConditions
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| index.ts | `packages/jest-environment-jsdom/src/index.ts` | ソース | JSDOMEnvironment実装 |
| package.json | `packages/jest-environment-jsdom/package.json` | 設定 | パッケージ定義 |
| index.ts | `packages/jest-environment-jsdom-abstract/src/index.ts` | ソース | BaseJSDOMEnvironment実装 |
| package.json | `packages/jest-environment-jsdom-abstract/package.json` | 設定 | パッケージ定義 |
