機能仕様書: Unity Test Execution（ユニットテスト実行）機能

[akiojin]

Spec

機能仕様書: Unity Test Execution（ユニットテスト実行）機能

機能ID: SPEC-e7c9b50c
作成日: 2025-10-17
ステータス: 完了
入力: Unity NUnitテストの実行要求、フィルタ、テストモード、結果エクスポート設定

実行フロー (main)

1. 入力からテスト実行要件を解析
   → テストモード（EditMode/PlayMode/All）の特定
   → フィルタ条件（クラス名、名前空間、カテゴリ）の抽出
2. Unity Test Runner APIの準備
   → TestRunnerApiインスタンスの作成
   → テストフィルタの構築
3. テスト実行
   → 指定されたテストの実行開始
   → リアルタイム進捗の通知（オプション）
4. テスト結果の収集
   → 成功/失敗/スキップの集計
   → エラーメッセージとスタックトレースの取得
5. 結果のフォーマット
   → JSON形式での結果整形
   → NUnit XML形式でのエクスポート（オプション）
6. 結果の返却
   → テスト結果サマリと詳細情報
7. 戻り値: SUCCESS（テスト結果）

---

⚡ クイックガイドライン

• ✅ AIエージェントによる自動テスト実行とCI/CD統合の必要性に焦点
• ❌ 内部的なUnity Test Runner APIの実装詳細やNUnitフレームワークの仕組みは避ける
• 👥 ゲーム開発者・QAエンジニア・AIエージェント向けに記述

---

ユーザーシナリオ＆テスト

主要ユーザーストーリー

開発者として、コード変更後にすぐにテストを実行して結果を確認したい。AIエージェントとして、ユーザーの指示に従ってUnityテストを実行し、失敗したテストを報告したい。

受け入れシナリオ

1. 前提 Unityプロジェクトにテストが存在する、実行 全EditModeテストを実行、結果 全テスト結果が返される
2. 前提 特定のテストクラスのみ実行したい、実行 フィルタでクラス名を指定、結果 そのクラスのテストのみが実行される
3. 前提 PlayModeテストを実行したい、実行 testMode=PlayModeで実行、結果 PlayModeテストが実行される
4. 前提 テストが失敗した、実行 テスト実行、結果 失敗したテストの詳細（エラーメッセージ、スタックトレース）が返される
5. 前提 テスト結果をXMLでエクスポートしたい、実行 exportPath指定で実行、結果 NUnit XML形式でファイルが出力される
6. 前提 テスト実行の進捗を知りたい、実行 includeProgress=trueで実行、結果 リアルタイムで進捗が通知される
7. 前提 カテゴリでフィルタしたい、実行 filter="Integration"で実行、結果 Integrationカテゴリのテストのみが実行される

エッジケース

• テストが1つも存在しない場合、どう処理するか? → 0件のテスト実行結果を返す（エラーにしない）
• テスト実行中にUnityがクラッシュした場合、どうなるか? → タイムアウトエラーを返す
• 無効なフィルタを指定した場合、どう処理するか? → 警告を返し、フィルタにマッチするテストが0件であることを通知
• PlayModeテストがランタイムエラーを起こした場合、どう処理するか? → エラーをキャプチャして失敗として報告
• 同時に複数のテスト実行要求が来た場合、どう処理するか? → 最初の実行が完了するまで待機、または拒否

要件

機能要件

• FR-001: ユーザーはMCPツール経由で全Unity NUnitテストを実行できる必要がある
• FR-002: システムは3種類のテストモード（EditMode/PlayMode/All）をサポートする必要がある
• FR-003: ユーザーはテストクラス名でフィルタリングできる必要がある
• FR-004: ユーザーは名前空間でフィルタリングできる必要がある
• FR-005: ユーザーはカテゴリでフィルタリングできる必要がある
• FR-006: システムはテスト結果サマリ（総数、成功数、失敗数、スキップ数）を返す必要がある
• FR-007: システムはテスト実行時間（秒）を測定して返す必要がある
• FR-008: 失敗したテストのエラーメッセージを返す必要がある
• FR-009: 失敗したテストのスタックトレースを返す必要がある
• FR-010: ユーザーは詳細モードで各テストの個別結果を取得できる必要がある
• FR-011: システはNUnit XML形式でテスト結果をエクスポートできる必要がある
• FR-012: ユーザーはエクスポートパスを指定できる必要がある
• FR-013: システムはリアルタイムでテスト進捗を通知できる必要がある（オプション）
• FR-014: システムはテスト実行中にキャンセルできる必要がある（オプション）
• FR-015: システムはテストが存在しない場合でもエラーにならない必要がある
• FR-016: PlayModeテスト実行時、ドメインリロードが発生してもテスト結果を取得できるように、実行中状態（runId/testMode）をリロード非依存で保存し、リロード後にTestRunnerApi・コールバックを再登録して完了通知を受け取れること
• FR-017: run_tests/get_test_status のレスポンスに runId と testMode を常時含め、リロード直後は「再同期中」であることが判別できる状態コードを返すこと
• FR-018: PlayModeテストにおいて途中経過や完了結果のファイル書き出しをデフォルトで行わない（オプトインでのみ許可）こと
• FR-019: get_test_status が idle を返すのは「テスト未実行」または明示的に終了した場合に限り、リロード直後に実行中ランがある場合は running もしくは「再同期中」を返すこと
• FR-020: get_compilation_state はドメインリロード後でも直近のコンパイル完了時刻を返すため、完了時刻を永続化（EditorPrefsなどリロード非依存のストレージ）して復元すること
• FR-021: コンパイル中（EditorApplication.isCompiling==true）はテスト実行を開始してはならない。run_tests はコンパイル完了を待つか、実行を拒否して理由を返すこと
• FR-022: コンソールにコンパイルエラーが残っている場合（最新のコンパイル後にエラーCount>0）はテスト実行を拒否し、エラー概数と最終コンパイル時刻を返すこと
• FR-023: read_console の logTypes は Log / Warning / Error のみとし、Error には Exception/Assert を含めて取得できること（簡易なエラー系一括取得のため）。その他の型表記は許容しない。
• FR-024: PlayModeテストでドメインリロードや接続断が発生しても、get_test_status は running → completed（またはウォッチドッグによる明示的なerror:RUNNER_TIMEOUT）へ確実に遷移し、idle に落ちて結果を失うことがないこと。ウォッチドッグ閾値と動作はテストで担保する。

非機能要件

• NFR-001: テスト実行開始は1秒以内に開始する必要がある
• NFR-002: テスト進捗通知は500ms以内に送信される必要がある
• NFR-003: 100個のテスト実行は30秒以内に完了する必要がある（平均）
• NFR-004: テスト実行がタイムアウトする場合、適切なエラーメッセージを返す必要がある
• NFR-005: XML エクスポートは1秒以内に完了する必要がある（1000テスト以下の場合）

主要エンティティ

• TestExecutionRequest: テストモード、フィルタ、詳細フラグ、エクスポートパスを含む実行要求
• TestResult: テスト名、ステータス（Passed/Failed/Skipped）、実行時間、出力を含む個別結果
• TestSummary: 総数、成功数、失敗数、スキップ数、合計実行時間を含むサマリ情報
• TestFailure: テスト名、エラーメッセージ、スタックトレースを含む失敗情報
• TestProgress: 現在のテスト番号、総テスト数、現在実行中のテスト名を含む進捗情報

---

レビュー＆受け入れチェックリスト

コンテンツ品質

• 実装詳細なし（言語、フレームワーク、API）
• ユーザー価値とビジネスニーズに焦点
• 非技術関係者向けに記述
• すべての必須セクション完成

要件完全性

• [要明確化]マーカーが残っていない
• 要件はテスト可能で曖昧さがない
• 成功基準は測定可能
• スコープが明確に境界付けられている
• 依存関係と前提条件が識別されている

---

実行ステータス

• ユーザー説明を解析済み
• 主要概念を抽出済み
• 曖昧さをマーク済み
• ユーザーシナリオを定義済み
• 要件を生成済み
• エンティティを識別済み
• レビューチェックリスト合格

---

参考実装（予定）

実装ファイル（作成予定）

• unity-cli/src/handlers/test/TestRunToolHandler.js
• unity-cli/src/handlers/test/TestGetStatusToolHandler.js
• UnityCliBridge/Packages/unity-cli-bridge/Editor/Handlers/TestExecutionHandler.cs

技術詳細（実装時に記載）

• Unity Test Runner API (UnityEditor.TestTools.TestRunner.Api)
• TestRunnerApi.Execute() によるテスト実行
• NUnit XML フォーマット生成
• リアルタイム進捗通知（TCP経由）
• テストフィルタの構築（Filter クラス使用）

---

関連仕様書

この機能は独立した新機能ですが、以下の既存機能と連携します：

• SPEC-9d2bc43b: Unity MCP基本接続機能（TCP通信基盤）
• SPEC-2e6d9a3b: コンソール管理機能（テスト実行時のログ管理）
• SPEC-3d9b5f4e: Editor制御機能（Editor状態管理）

---

実装優先度

優先度: 高

理由:

• AIエージェントによる自動テスト実行はTDD/CI/CDワークフローで重要
• unity-cliを使用するユーザーの開発体験向上に直結
• 既存のUnity Test Runner APIを活用できるため実装コストは中程度

Plan

実装計画: Unity Test Execution（ユニットテスト実行）機能

機能ID: SPEC-e7c9b50c | ステータス: 実装完了

概要

本機能は既に実装済みです。このplan.mdは実装完了後に作成されました。

実装状況

• ✅ Phase 0: Research完了
• ✅ Phase 1: Design完了
• ✅ Phase 2: Task planning完了
• ✅ Phase 3: Tasks実装完了
• ✅ Phase 4: 実装完了
• ✅ Phase 5: テスト完了

参考実装

実装詳細については spec.md の「参考実装」セクションを参照してください。

---

本ドキュメントは実装完了後に作成されました

Tasks

タスク: Unity Test Execution（ユニットテスト実行）機能

機能ID: SPEC-e7c9b50c | ステータス: 完了

実装状況

本機能は既に実装済みです。すべてのタスクが完了しています。

完了済みタスク

• 機能設計
• コア実装
• テスト実装
• ドキュメント作成

参考

実装詳細については spec.md および plan.md を参照してください。

---

本ドキュメントは実装完了後に作成されました

TDD

TODO

Research

TODO

Data Model

TODO

Quickstart

TODO

Contracts

Artifact files under contracts/ are managed in issue comments with contract:<name> entries.

Checklists

Artifact files under checklists/ are managed in issue comments with checklist:<name> entries.

Acceptance Checklist

• Add acceptance checklist

[akiojin]

gwt-spec ドメイン再編により #155 に統合