/timeout-fix

description: テスト実行のタイムアウト問題を分析し、テストの高速化または適切な分離を行います。auto-debugから委譲される他、ユーザが直接呼び出すことも可能です。
allowed-tools: Read, Glob, Grep, Task, Edit, Write
argument-hint: "[テストファイルパス]"

テストのタイムアウト問題を解消して。

context

test_command: {{test_command}} (テスト実行コマンド。未指定の場合は npm test)
test_file: {{test_file}} (タイムアウトしたテストファイル。未指定の場合は全テスト)
timeout_seconds: {{timeout_seconds}} (タイムアウトした秒数)
max_retry: 2 (修正の最大リトライ回数)
execution_timeout: 120 (テスト再実行時のタイムアウト秒数)

step

step0: プロジェクトコンテキストの確認

以下のファイルが存在する場合は読み取り、テスト実行方法や性能要件を把握する:

• `CLAUDE.md` — テスト実行方法、タイムアウト設定、プロジェクト固有の指示
• `README.md` — テスト実行環境、パフォーマンス要件
• `AGENTS.md` — エージェント向けの開発ルール

test_command が未指定の場合は、これらの情報から適切なテストコマンドを決定する。

step1: タイムアウト原因の分析

1. **テストファイルと関連コードの読み取り**

• 対象テストファイルを Read tool で読み取り
• テスト対象の実装ファイルを特定

2. **原因分析**（Task tool, subagent_type: Explore, thoroughness: **medium**）

• 以下のタイムアウト原因パターンに沿って分析:
• **非効率な処理**: N+1クエリ、不要なループ、大量データの逐次処理
• **外部API呼び出しのハング**: タイムアウト未設定のHTTPリクエスト、未応答のサービス
• **デッドロック/無限ループ**: Promise未解決、イベントループブロック、再帰の終了条件欠如
• **大量テストデータ**: 不必要に大きなテストデータセット
• **テストのセットアップ過重**: beforeAll/beforeEachでの重い初期化処理
• **リソースリーク**: 未クローズの接続、ストリーム、ファイルハンドル
• 最も可能性の高い原因を特定し、修正方針を決定

step2: 修正の試行

原因に応じた修正を実施（general-purpose subagent）:

1. **非効率な処理の場合**

• テスト対象コードの最適化（テスト範囲内で可能な場合）
• テスト側でのデータ量削減
• バッチ処理への変更

2. **外部API呼び出しのハングの場合**

• テストでのモック導入（実際のAPI呼び出しを回避）
• テスト対象コードにタイムアウト設定が不足している場合はレポートに記載
• テスト用のAbortController / タイムアウト設定追加

3. **デッドロック/無限ループの場合**

• テストコード内のPromise解決パターンを修正
• 無限ループの終了条件修正
• テスト用のタイムアウトガード追加

4. **大量テストデータの場合**

• テストデータセットの削減（本質を損なわない範囲で）
• テストファクトリの最適化

5. **テストのセットアップ過重の場合**

• 不要な初期化の削除
• 共有セットアップの最適化（beforeAllへの移動等）

6. **リソースリークの場合**

• afterAll/afterEachでの適切なクリーンアップ追加
• 接続のクローズ処理追加

step3: 再実行による確認

1. **修正後のテストを実行**（明示的タイムアウト設定）

   timeout {{execution_timeout}} {{test_command}} -- {{test_file}} 2>&1

2. **結果判定**

• **タイムアウトせず成功**: 修正完了。step5（レポート）へ
• **タイムアウトせず失敗**: テストエラーは別問題。タイムアウト改善は成功としてレポート
• **再度タイムアウト**: retry_count < max_retry → 別のアプローチで step1 に戻る
• **retry_count >= max_retry**: step4（テスト分離）へ

step4: テストの分離

修正でタイムアウトを解消できなかった場合、テストを通常実行から分離:

1. **分離方法の決定**

• Jest: `describe.skip` + 専用設定ファイルでの実行（`jest.config.slow.js`）
• Playwright: タグ付け（`@slow`）+ フィルター実行
• pytest: `@pytest.mark.slow` マーカー付与

2. **分離の実施**

• テストに適切なマーカー/タグを付与
• 通常のテスト実行から除外される設定を確認
• 分離されたテストの個別実行方法を記録

3. **通常テストの実行確認**

   {{test_command}} 2>&1

• 分離されたテストが除外されていることを確認

step5: 結果レポート

# timeout-fix 結果レポート

## 結果: [改善成功 / 分離成功 / 改善失敗]

## 対象テスト
- ファイル: {{test_file}}
- 元のタイムアウト: {{timeout_seconds}}秒

## タイムアウト原因
- 原因分類: [非効率処理 / 外部APIハング / デッドロック / 大量データ / セットアップ過重 / リソースリーク]
- 詳細: [具体的な原因]

## 修正内容
（改善成功の場合）
- 修正ファイル: [ファイルパス]
- 修正内容: [具体的な変更内容]
- 改善後の実行時間: X秒

## テスト分離
（分離の場合）
- 分離方法: [skip + 専用設定 / タグ付け / マーカー]
- 個別実行方法: [実行コマンド]
- 推奨対応: [根本的な改善のための方針]

rule

NEVER: テストの削除（分離はOKだが削除はNG） NEVER: テストの期待値を変更してタイムアウトを回避 NEVER: 実装コードの本質的なロジック変更（テスト通過のための最適化は除く） MUST: 分離されたテストの個別実行方法を必ずレポートに記載 MUST: テスト分離時はスキップ理由をコメントとして記載 MUST: 各リトライで前回と異なるアプローチを試みる