gwt-spec: PlayMode・テスト・Profiler

[akiojin]

Spec

Background

ドメイン仕様書: PlayMode・テスト・Profiler

作成日: 2026-04-05
ステータス: active

Unity EditorのPlayMode（再生モード）の制御、EditMode/PlayModeテストの実行と結果取得、およびProfilerによるパフォーマンス計測を統合するドメイン。Play/Pause/Stop制御とドメインリロード対応、NUnitベースのテスト実行（フィルタ・XML出力・進捗通知対応）、Profilerデータの記録・リアルタイムメトリクス取得を含む。AIエージェントによる自動テスト実行とパフォーマンス計測の自動化を実現する。

Ubiquitous Language

TODO

User Stories

TODO

Acceptance Scenarios

TODO

Edge Cases

TODO

Functional Requirements

TODO

Non-Functional Requirements

TODO

Success Criteria

TODO

---

Domain-Specific Details

対象コマンド群

PlayMode制御

• playmode play - PlayMode開始（ドメインリロード・自動再接続対応）
• playmode pause - 一時停止/レジューム
• playmode stop - EditMode復帰
• playmode state - エディタ状態取得（isPlaying、isPaused、プラットフォーム等）
• playmode wait - 特定状態への待機（タイムアウト・ポーリング対応）

テスト実行

• test run - NUnitテスト実行（EditMode/PlayMode/All）
• test status - テスト実行状態取得（runId、再同期中判定）
• test filter - テストフィルタリング（クラス名、名前空間、カテゴリ）
• test export - NUnit XML形式結果エクスポート
• compilation state - コンパイル状態取得（完了時刻永続化）
• console read - コンソールログ取得（Log/Warning/Error）

Profiler

• profiler start - プロファイリング開始（セッションID発行）
• profiler stop - プロファイリング停止（.dataファイル保存）
• profiler metrics - リアルタイムメトリクス取得（CPU、メモリ、GC、描画コール等）
• profiler status - プロファイリング状態確認

完了済み機能

• ✅ PlayMode制御機能（旧 機能仕様書: PlayMode制御機能 #78）

  • Play/Pause/Stop/状態取得/状態待機、ドメインリロード自動再接続
  • 13個の機能要件を定義・実装済み
  • ソフトキャッシュによる状態取得最適化、ポーリングベース状態待機

• ✅ Unity Test Execution機能（旧 機能仕様書: Unity Test Execution（ユニットテスト実行）機能 #96）

  • EditMode/PlayModeテスト実行、フィルタリング、NUnit XML出力、進捗通知
  • 24個の機能要件を定義・実装済み
  • PlayModeドメインリロード対応（runId永続化・再同期）、コンパイルエラーガード、ウォッチドッグ

Plan

Unity Profilerパフォーマンス計測（旧 #68 より継承）

1. Phase 0: Research - Unity ProfilerRecorder API/ProfilerCategory調査
2. Phase 1: Design - ProfilerSession/ProfilerMetric データモデル定義、契約作成
3. Phase 2: TDD - Contract tests (RED) → 実装 → GREEN
4. Phase 3: 実装
   • Unity側: ProfilerHandler.cs（記録開始/停止、メトリクス取得、状態管理）
   • Node側: ProfilerToolHandler.js（4つのMCPツール）
5. Phase 4: 統合検証 - .dataファイルのProfiler Window互換、リアルタイムメトリクス精度
6. Phase 5: 仕上げ - ドキュメント、ログ出力、既存機能との操作感統一

Profiler設計方針

• 4つのMCPツール: profiler_start, profiler_stop, profiler_metrics, profiler_status
• セッション管理: 同時に1つのセッションのみ（重複開始はエラー）
• メトリクス: カテゴリ別フィルタ、指定メトリクスのみ取得オプション
• 既存VideoCapture/Screenshot機能と同じ操作感を目指す

Tasks

Profiler実装（旧 #68）

Phase 0-1: Research/Design

• Research完了（ProfilerRecorder API、ProfilerCategory調査）
• Design完了（data-model.md、contracts/、quickstart.md作成）

テストファースト (RED)

• profiler_start contract test
• profiler_stop contract test
• profiler_metrics contract test
• profiler_status contract test
• すべてのContract testsが失敗 (RED確認)

Unity側実装

• ProfilerHandler.cs スケルトン作成
• profiler_start: Profiler.BeginSession + .dataファイルパス設定
• profiler_stop: Profiler.EndSession + ファイル保存確認
• profiler_metrics: ProfilerRecorderでリアルタイムメトリクス取得
• profiler_status: セッション状態・経過時間・ファイルパス返却
• UnityCliBridgeにProfilerHandlerルーティング追加

Node側実装

• ProfilerStartToolHandler.js / ProfilerStopToolHandler.js 実装
• ProfilerMetricsToolHandler.js / ProfilerStatusToolHandler.js 実装
• handlers/index.js でエクスポート、MCPサーバーで登録

統合・検証

• すべてのContract testsが合格 (GREEN確認)
• .dataファイルがUnity Profiler Windowで正常に開けることを確認
• リアルタイムメトリクスが正確に取得できることを確認
• ドキュメント更新（README、quickstart）

TDD

Profiler

• RED: profiler-start.test.js, profiler-stop.test.js, profiler-metrics.test.js, profiler-status.test.js の contract tests
• GREEN: Unity側 ProfilerHandler + Node側ハンドラー実装後に全テストパス
• REFACTOR: 重複コード削除、既存ハンドラーとの共通パターン抽出

Profiler仕様詳細 (旧 #68, 下書き)

注記: 本仕様は旧Node.js/MCPアーキテクチャ向けに記述。Rust CLI実装時に適宜アダプテーション必要。

ユーザーストーリー

US-1 パフォーマンス計測の記録と保存 (P1)
開発者/QAが実行中のパフォーマンスデータを記録し、Unity Profiler Windowで分析可能な.dataファイルとして保存する。

• GWT 1: 計測開始指示 → セッションID返却
• GWT 2: 計測停止指示 → .dataファイル保存
• GWT 3: .dataファイル → Profiler Windowで時系列グラフ表示可能
• GWT 4: 重複開始 → エラー + 既存セッションID通知

US-2 リアルタイムメトリクス取得 (P2)
実行中にCPU時間、メモリ使用量、GC回数、描画コール数等をJSON形式でリアルタイム取得。

• GWT 1: メトリクス一覧取得 → カテゴリ別にメトリクス名返却
• GWT 2: 現在値取得 → 最新数値をJSON返却
• GWT 3: 特定メトリクス指定 → 指定分のみ返却

US-3 プロファイリング状態確認 (P3)
現在の記録状態、開始時刻、経過時間、残り時間を確認可能。

• GWT 1: 非記録中 → idle状態返却
• GWT 2: 記録中 → セッションID/開始時刻/経過時間返却
• GWT 3: maxDurationSec設定時 → 残り時間も返却

機能要件

ID	要件
FR-001	Profilerによるパフォーマンスデータ記録を開始できる
FR-002	記録を停止し.data形式でファイル保存できる
FR-003	.dataファイルはUnity Profiler Windowで開ける標準形式
FR-004	現在の状態（実行中/停止、セッションID、経過時間）を返却
FR-005	利用可能メトリクス一覧を返却
FR-006	指定メトリクスのリアルタイム値を取得
FR-007	重複開始を拒否しエラーメッセージ返却
FR-008	自動停止時間（maxDurationSec）を設定可能
FR-009	.unity/capture/ に統一的に保存
FR-010	セッションごとに一意IDを生成

エッジケース

• クラッシュ時は次回起動で状態リセット
• 保存先ディレクトリ不在/権限不足時の適切なエラー
• 未開始で停止要求時のエラー
• 長時間（数時間）記録でのメモリ制限
• 同一セッションID複数回停止の処理

データモデル（7エンティティ）

ProfilerSession (Unity側): sessionId(GUID), isRecording, startedAt, outputPath, maxDurationSec, recorders

ProfilerMetric (共通): category(CPU/Memory/Rendering/GC), name, value(long), unit(bytes/count/ms)

ProfilerStartRequest: mode(normal/deep), recordToFile(bool), metrics(string[]), maxDurationSec

ProfilerStartResponse: sessionId, startedAt, isRecording, outputPath

ProfilerStopResponse: sessionId, outputPath, duration, frameCount, metrics

ProfilerStatusResponse: isRecording, sessionId, startedAt, elapsedSec, remainingSec

ProfilerMetricsResponse: categories → {name, metrics[]}

Research決定事項（5件）

1. ProfilerDriver API: ProfilerDriver.enabled + ProfilerDriver.SaveProfile() を使用
2. ProfilerRecorder API: ProfilerRecorder.StartNew() でリアルタイム取得
3. メトリクス一覧: ProfilerRecorderHandle.GetAvailable() で動的取得
4. 定期処理: EditorApplication.update でVideoCapture同様に処理
5. セッション状態管理: 静的フィールドで保持（VideoCaptureHandlerと同パターン）

技術制約・前提・成功基準

• Unity Editor環境でのみ動作（ビルド済みアプリ不可）
• UnityEditorInternal.ProfilerDriver + Unity.Profiling.ProfilerRecorder
• 保存先: .unity/capture/ 固定
• 性能目標: リアルタイムメトリクス <1秒、開始/停止 <500ms、10分以上でメモリリークなし
• .dataファイルがProfiler Windowで正常に開ける
• CI/CDでパフォーマンスリグレッション検出可能
• 既存Screenshot/Video機能と同じ操作感・保存先統一

旧Issue参照

• 機能仕様書: PlayMode制御機能 #78 機能仕様書: PlayMode制御機能 (完了)
• 機能仕様書: Unity Test Execution（ユニットテスト実行）機能 #96 機能仕様書: Unity Test Execution機能 (完了)
• 機能仕様書: Unity Profilerパフォーマンス計測 #68 機能仕様書: Unity Profilerパフォーマンス計測 (下書き)