# 非機能要件定義書

## 概要

本ドキュメントは、Jest（JavaScript テスティングフレームワーク）の非機能要件を定義するものです。Jestは55以上のパッケージを含むモノレポ構成のオープンソースプロジェクトであり、性能、可用性、セキュリティ、拡張性、保守性、運用・監視の各観点から要件を整理しています。

## 性能要件

### レスポンスタイム

| 処理種別 | 目標値 | 備考 |
| --- | --- | --- |
| 個別テストタイムアウト | 70,000ms（70秒）以内 | `testTimeout`設定で調整可能（デフォルト: 5,000ms） |
| 遅いテスト閾値 | 5秒以内 | `slowTestThreshold`設定で定義、超過時にレポートで警告表示 |
| オープンハンドル検出タイムアウト | 1,000ms以内 | `openHandlesTimeout`設定で定義 |
| CIテスト実行タイムアウト | 10分以内 | GitHub Actions ワークフローで定義（`timeout_minutes: 10`） |

### スループット

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| 最大同時並列数 | CPU コア数の50%（デフォルト） | `maxWorkers`設定で調整可能（`'50%'`または具体的な数値） |
| 最大同時実行テスト数 | 5 | `maxConcurrency`設定で定義 |
| ウォッチモード時の並列数 | CPU コア数の50% | CPU リソースを圧迫しないよう制限 |
| ワーカーリトライ回数 | 最大3回 | `maxRetries`設定で定義 |
| CI シャード分割 | 4分割（Ubuntu/Windows）、3分割（macOS） | 並列実行による高速化 |

### メモリ管理

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| アイドルメモリ制限 | 設定可能 | `idleMemoryLimit`でワーカープロセスのメモリ使用量を制限 |
| リソース制限 | 設定可能 | `resourceLimits`でワーカースレッドのリソース制限を定義 |
| メモリリーク検出 | 有効化可能 | `detectLeaks`オプションで検出テストを実行 |

## 可用性要件

| 項目 | 目標値 | 備考 |
| --- | --- | --- |
| クロスプラットフォーム対応 | Ubuntu, macOS, Windows | CI/CDで全プラットフォームでのテストを実施 |
| Node.js バージョン対応 | 18.14.0+, 20.0.0+, 22.0.0+, 24.0.0+ | `engines`フィールドで定義 |
| TypeScript 互換性 | 5.4+ | `verify-old-ts`スクリプトで検証 |
| テスト再試行 | 最大3回 | CIワークフローで`max_attempts: 3`を設定 |
| ワーカープロセス再起動 | 自動 | 異常終了時に自動再起動（最大3回のリトライ） |
| ウォッチモード継続性 | 無停止 | ファイル変更検知で自動的にテストを再実行 |

## セキュリティ要件

### 脆弱性対応

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| 脆弱性報告 | GitHubのプライベート報告機能を使用 | SECURITY.md で定義 |
| 初期応答 | 6営業日以内 | OpenJS Foundation CNA へのエスカレーションも可能 |
| 対応完了 | 14日以内に進捗報告 | CVE発行はOpenJS CNA経由 |
| 公開基準 | 修正または緩和策が利用可能になった時点 | セキュリティアドバイザリを公開 |

### プロセス分離

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| サンドボックス実行 | `sandboxInjectedGlobals`設定で分離 | テスト環境のグローバル変数を制限 |
| ワーカープロセス分離 | 子プロセスまたはワーカースレッドで実行 | `workerThreads`オプションで切替可能 |
| 完全なプロセス分離 | `idleMemoryLimit: 0`で各テスト後にプロセス再起動 | テストファイル間の完全な分離を実現 |

### ファイルシステムアクセス

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| キャッシュディレクトリ | UIDベースで分離 | マルチユーザー環境での権限問題を回避 |
| 一時ファイル | システムtmpdir配下に作成 | `/tmp/jest_{uid}`形式 |

## 拡張性要件

### プラグインアーキテクチャ

| 拡張ポイント | 説明 | 設定項目 |
| --- | --- | --- |
| カスタムレポーター | テスト結果の出力形式をカスタマイズ | `reporters` |
| カスタムトランスフォーマー | ソースコードの変換処理をカスタマイズ | `transform` |
| カスタムリゾルバー | モジュール解決ロジックをカスタマイズ | `resolver` |
| カスタムランナー | テスト実行ロジックをカスタマイズ | `runner` |
| カスタム環境 | テスト実行環境をカスタマイズ | `testEnvironment` |
| カスタムシーケンサー | テスト実行順序をカスタマイズ | `testSequencer` |
| カスタム依存抽出器 | 依存関係の抽出ロジックをカスタマイズ | `dependencyExtractor` |
| スナップショットシリアライザー | スナップショットの出力形式をカスタマイズ | `snapshotSerializers` |
| ウォッチプラグイン | ウォッチモードの機能を拡張 | `watchPlugins` |

### モジュール拡張

| 項目 | 説明 | 備考 |
| --- | --- | --- |
| モジュールファイル拡張子 | 10種類のデフォルト拡張子対応 | js, mjs, cjs, jsx, ts, mts, cts, tsx, json, node |
| ESM対応 | `extensionsToTreatAsEsm`で追加拡張子を定義可能 | ES Modules のネイティブサポート |
| プリセット | 設定のベースとなるプリセットを定義可能 | `preset`設定で指定 |

### マルチプロジェクト対応

| 項目 | 説明 | 備考 |
| --- | --- | --- |
| プロジェクト分離 | 複数プロジェクトを単一実行で処理 | `projects`設定で定義 |
| ワークスペース対応 | Yarn Workspaces, Lerna対応 | モノレポ構成をサポート |

## 保守性要件

### コード品質

| 項目 | 基準 | 備考 |
| --- | --- | --- |
| 言語 | TypeScript | 全ての新規コードはTypeScriptで記述 |
| コードスタイル | ESLint + Prettier | 自動フォーマット・静的解析を適用 |
| インデント | 2スペース | タブ禁止 |
| 行長制限 | 80文字（推奨） | 可読性の維持 |
| 著作権ヘッダー | 全ソースファイルに必須 | CIで検証 |
| 型チェック | TypeScript 5.4+互換 | `verify-old-ts`で検証 |

### テストカバレッジ

| 項目 | 基準 | 備考 |
| --- | --- | --- |
| カバレッジプロバイダー | Babel（デフォルト） | `coverageProvider`で変更可能 |
| カバレッジレポーター | json, text, lcov, clover | `coverageReporters`でカスタマイズ可能 |
| カバレッジ閾値 | 設定可能 | `coverageThreshold`で最小カバレッジを定義 |
| カバレッジ収集 | 4シャード並列で実行 | CIでの効率的な収集 |

### 依存関係管理

| 項目 | 基準 | 備考 |
| --- | --- | --- |
| パッケージマネージャー | Yarn 4.12.0（Berry） | `corepack enable`で有効化 |
| ロックファイル | `yarn.lock`で固定 | `--immutable`フラグでCI時の整合性を保証 |
| 制約検証 | Yarn Constraints | 重複依存の検出、バージョン整合性の検証 |
| 重複排除 | `yarn dedupe` | 依存関係の重複を検出・修正 |

## 運用・監視要件

### CI/CD パイプライン

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| メインCI | GitHub Actions | push, PR, merge_groupで実行 |
| 静的解析 | ESLint, Prettier, TypeScript | 全コード変更時に実行 |
| テストマトリクス | 3 OS x 4 Node バージョン x 4 シャード | 包括的なテスト実行 |
| コンカレンシー制御 | ワークフロー単位で制限 | 同一ブランチでの重複実行をキャンセル |
| キャッシュ | Yarn キャッシュを事前準備 | ビルド時間の短縮 |
| 夜間テスト | Nightly ワークフロー | 最新Node.jsバージョンでのテスト |

### 監視・通知

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| テスト結果通知 | デスクトップ通知対応 | `notify`オプションで有効化 |
| 通知モード | failure-change（デフォルト） | `notifyMode`でカスタマイズ可能 |
| 詳細出力 | `verbose`オプション | 個別テスト結果を出力 |
| カバレッジレポート | Codecov連携 | PRにカバレッジ変化を表示 |
| GitHub Actions Reporter | CIでのエラー表示 | アノテーションでエラー位置を表示 |

### キャッシュ管理

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| キャッシュ有効 | デフォルトで有効 | `cache: true` |
| キャッシュディレクトリ | システムtmpdir配下 | `cacheDirectory`でカスタマイズ可能 |
| キャッシュクリア | `jest --clearCache` | 問題発生時にキャッシュをクリア |
| 変換結果キャッシュ | ファイル変換結果をキャッシュ | 再ビルド時間の短縮 |
| HasteMapキャッシュ | ファイルシステムクロールの結果をキャッシュ | 起動時間の短縮 |

### ファイル監視

| 項目 | 内容 | 備考 |
| --- | --- | --- |
| Watchman対応 | デフォルトで有効 | `watchman: true` |
| FSEvents対応 | macOSで利用可能 | 高速なファイル監視 |
| NodeWatcher | フォールバック用 | Watchman未インストール時に使用 |
| 監視除外パターン | 設定可能 | `watchPathIgnorePatterns`で定義 |

## 備考

- 本ドキュメントはJest v30.2.0のコードベースを基に作成しています
- 設定値はデフォルト値を記載しており、各プロジェクトの要件に応じてカスタマイズ可能です
- パフォーマンス目標値は実行環境により変動する可能性があります
- セキュリティ要件はOpenJS Foundationのポリシーに準拠しています
