unity-test-runner

Unity Test Runner

概要

このスキルを使用すると、コマンドラインから Unity Test Framework のテストを自動的に実行し、分析できます。Unity Editor のインストールを各プラットフォーム（Windows/macOS/Linux）で検出し、テストパラメーターを設定して、EditMode または PlayMode でテストを実行し、NUnit XML の結果を解析して、実行可能な対策を含む詳細な失敗レポートを生成するまで、テストのワークフロー全体に対応します。

このスキルを使用する場面

次の場合にこのスキルを使用してください：

• コマンドラインから Unity Test Framework のテストを実行するとき
• ゲームロジックの検証のために PlayMode または EditMode のテストを実行するとき
• テストの失敗を分析し、失敗レポートを生成するとき
• Unity のテストを CI/CD パイプラインに統合するとき
• 詳細なスタックトレースとファイルの場所を使ってテストの失敗をデバッグするとき
• コミット前に Unity プロジェクトの変更を検証するとき

ユーザーからのリクエスト例：

• 「プロジェクト内の Unity テストをすべて実行して」
• 「PlayMode テストを実行して、結果を見せて」
• 「Combat カテゴリのテストを実行して」
• 「Unity のテストが成功しているか確認して」
• 「EditMode テストだけを実行して」

ワークフロー

このスキルを呼び出したときは、次のワークフローに従ってください。

1. Unity Editor のインストールを検出する

find-unity-editor.js スクリプトを使用して、Unity Editor を自動的に検出します。

node scripts/find-unity-editor.js --json

スクリプトの動作：

• プラットフォームごとの既定のインストールパスを検索します
• インストール済みの Unity のすべてのバージョンを検出します
• 既定では最新バージョンを返します
• --version <version> フラグを指定すると、特定のバージョンを対象にできます

出力：

{
  "found": true,
  "editorPath": "C:\\Program Files\\Unity\\Hub\\Editor\\2021.3.15f1\\Editor\\Unity.exe",
  "version": "2021.3.15f1",
  "platform": "win32",
  "allVersions": ["2021.3.15f1", "2020.3.30f1"]
}

複数のバージョンが見つかった場合：

1. 利用可能なすべてのバージョンをユーザーに提示します
2. 使用するバージョンをユーザーに確認します
3. または、既定で最新バージョンを使用します

Unity Editor が見つからない場合：

• 検索したパスを含めてエラーを報告します
• Unity Editor のパスを手動で指定するようユーザーに依頼します
• 今後使用できるよう、そのパスを保存します

2. Unity プロジェクトのパスを確認する

クロスプラットフォームのチェックを使って、現在のディレクトリが有効な Unity プロジェクトであることを確認します。

// Use Read tool to check for Unity project indicators
Read({ file_path: "ProjectSettings/ProjectVersion.txt" })

// Use Glob to verify Assets directory exists
Glob({ pattern: "Assets/*", path: "." })

検証手順：

1. Assets/ ディレクトリが存在することを確認します
2. ProjectSettings/ProjectVersion.txt が存在することを確認します
3. ProjectVersion.txt を読み取り、Unity のバージョンを取得します
4. Editor のバージョンがプロジェクトのバージョンと一致しない場合は警告します

ProjectVersion.txt の例：

m_EditorVersion: 2021.3.15f1
m_EditorVersionWithRevision: 2021.3.15f1 (e8e88743f9e5)

3. テスト設定を構成する

テスト実行のパラメーターを決定します。パラメーターが指定されていない場合は、AskUserQuestion ツールを使用します。

必須設定：

• テストモード：EditMode、PlayMode、または Both
• テストプラットフォーム：EditMode テストでは「EditMode」を使用します。PlayMode ではプラットフォームを指定できます（例：「StandaloneWindows64」、「Android」、「iOS」）

任意設定：

• テストカテゴリ：セミコロン区切りのリスト（例：「Combat;AI;Physics」）
• テストフィルター：正規表現パターン、またはセミコロン区切りのテスト名
• 結果の出力パス：既定ではプロジェクトのルートにある TestResults.xml

設定例：

AskUserQuestion({
  questions: [{
    question: "Which test mode should be executed?",
    header: "Test Mode",
    multiSelect: false,
    options: [
      { label: "EditMode Only", description: "Fast unit tests without Play Mode" },
      { label: "PlayMode Only", description: "Full Unity engine tests" },
      { label: "Both Modes", description: "Run all tests (slower)" }
    ]
  }]
})

4. コマンドラインからテストを実行する

Unity のコマンドラインテストコマンドを作成して実行します。

コマンドの構成：

<UnityEditorPath> -runTests -batchmode -projectPath <ProjectPath> \
  -testPlatform <EditMode|PlayMode> \
  -testResults <OutputPath> \
  [-testCategory <Categories>] \
  [-testFilter <Filter>] \
  -logFile -

コマンド例：

EditMode テスト：

"C:\Program Files\Unity\Hub\Editor\2021.3.15f1\Editor\Unity.exe" \
  -runTests -batchmode \
  -projectPath "D:\Projects\MyGame" \
  -testPlatform EditMode \
  -testResults "TestResults-EditMode.xml" \
  -logFile -

カテゴリフィルターを指定した PlayMode テスト：

"C:\Program Files\Unity\Hub\Editor\2021.3.15f1\Editor\Unity.exe" \
  -runTests -batchmode \
  -projectPath "D:\Projects\MyGame" \
  -testPlatform PlayMode \
  -testResults "TestResults-PlayMode.xml" \
  -testCategory "Combat;AI" \
  -logFile -

実行時の注意事項：

• 実行時間の長いテストでは、run_in_background: true を指定して Bash ツールを使用します
• 適切なタイムアウトを設定します（既定値：5～10 分。テスト数に応じて調整してください）
• 進行状況を示す出力を監視します
• 標準出力と標準エラーの両方を取得します

実行例：

Bash({
  command: `"${unityPath}" -runTests -batchmode -projectPath "${projectPath}" -testPlatform EditMode -testResults "TestResults.xml" -logFile -`,
  description: "Execute Unity EditMode tests",
  timeout: 300000, // 5 minutes
  run_in_background: true
})

5. テスト結果を解析する

テストの完了後、parse-test-results.js を使用して NUnit XML の結果を解析します。

node scripts/parse-test-results.js TestResults.xml --json

スクリプトの出力：

{
  "summary": {
    "total": 10,
    "passed": 7,
    "failed": 2,
    "skipped": 1,
    "duration": 12.345
  },
  "failures": [
    {
      "name": "TestPlayerTakeDamage",
      "fullName": "Tests.Combat.PlayerTests.TestPlayerTakeDamage",
      "message": "Expected: 90\n  But was: 100",
      "stackTrace": "at Tests.Combat.PlayerTests.TestPlayerTakeDamage () [0x00001] in Assets/Tests/Combat/PlayerTests.cs:42",
      "file": "Assets/Tests/Combat/PlayerTests.cs",
      "line": 42
    }
  ],
  "allTests": [...]
}

結果の分析：

1. テストの概要統計を抽出します
2. 失敗したテストをすべて特定します
3. スタックトレースからファイルパスと行番号を抽出します
4. 失敗を種類（アサーション、例外、タイムアウト）別に分類します

6. テスト失敗を分析する

失敗したテストごとに、references/test-patterns.json を使用して失敗を分析します。

分析手順：

1. テストパターンのデータベースを読み込む：

Read({ file_path: "references/test-patterns.json" })

2. 失敗メッセージをパターンと照合する：

   • アサーション失敗：Expected: <X> But was: <Y>
   • Null 参照失敗：Expected: not null But was: <null>
   • タイムアウト失敗：TimeoutException|Test exceeded time limit
   • スレッドエラー：Can't be called from.*main thread
   • オブジェクトのライフタイムに関する問題：has been destroyed|MissingReferenceException

3. 失敗のカテゴリを特定する：

   • ValueMismatch：アサーション値が誤っています
   • NullValue：予期せず Null 参照になっています
   • Performance：タイムアウト、または実行速度が遅い状態です
   • TestSetup：セットアップ／ティアダウンの失敗です
   • ObjectLifetime：破棄されたオブジェクトにアクセスしています
   • Threading：誤ったスレッドで実行されています

4. 修正案を生成する：

   • test-patterns.json から一般的な解決策を読み込みます
   • 解決策を失敗パターンと照合します
   • 具体的なコード例を提示します

失敗分析の例：

**Test**: Tests.Combat.PlayerTests.TestPlayerTakeDamage
**Location**: Assets/Tests/Combat/PlayerTests.cs:42
**Result**: FAILED

**Failure Message**:
Expected: 90
  But was: 100

**Analysis**:
- Category: ValueMismatch (Assertion Failure)
- Pattern: Expected/actual value mismatch
- Root Cause: Player health not decreasing after TakeDamage() call

**Possible Causes**:
1. TakeDamage() method not implemented correctly
2. Player health not initialized properly
3. Damage value passed incorrectly

**Suggested Solutions**:
1. Verify TakeDamage() implementation:
   ```csharp
   public void TakeDamage(int damage) {
       health -= damage; // Ensure this line exists
   }

2. テストのセットアップを確認します：

   [SetUp]
   public void SetUp() {
       player = new Player();
       player.Health = 100; // Ensure proper initialization
   }
   

3. テストのアサーションを確認します：

   player.TakeDamage(10);
   Assert.AreEqual(90, player.Health); // Expected: 90
   

### 7. Generate Test Report

Create a comprehensive test report for the user:

**Report structure:**

```markdown
# Unity Test Results

## Summary
- **Total Tests**: 10
- **✓ Passed**: 7 (70%)
- **✗ Failed**: 2 (20%)
- **⊘ Skipped**: 1 (10%)
- **Duration**: 12.35s

## Test Breakdown
- **EditMode Tests**: 5 passed, 1 failed
- **PlayMode Tests**: 2 passed, 1 failed

## Failed Tests

### 1. Tests.Combat.PlayerTests.TestPlayerTakeDamage
**Location**: Assets/Tests/Combat/PlayerTests.cs:42

**Failure**: Expected: 90, But was: 100

**Analysis**: Player health not decreasing after TakeDamage() call.

**Suggested Fix**: Verify TakeDamage() implementation decreases health correctly.

---

### 2. Tests.AI.EnemyTests.TestEnemyChasePlayer
**Location**: Assets/Tests/AI/EnemyTests.cs:67

**Failure**: TimeoutException - Test exceeded time limit (5s)

**Analysis**: Infinite loop or missing yield in coroutine test.

**Suggested Fix**: Add `[UnityTest]` attribute and use `yield return null` in test loop.

---

## Next Steps
1. Review failed test locations and fix implementation
2. Re-run tests after fixes by re-invoking the skill
3. Consider adding more assertions for edge cases

レポートの提示：

• 書式設定された Markdown でレポートを提示します
• 重大な失敗を強調表示します
• すばやく該当箇所に移動できるよう、ファイル名と行番号を提示します
• ユーザーから依頼があれば、具体的な失敗の修正を支援します

ベストプラクティス

このスキルを使用する際は、次の点に注意してください。

1. 最初に EditMode テストを実行する - 実行が速く、基本的なロジックエラーを検出できます

   • Unity 固有の機能には PlayMode テストを使用します
   • 純粋な C# のロジックやデータ構造には EditMode を使用します

2. テストカテゴリを使用する - テストを絞り込んで反復を速めます

   • -testCategory "Combat" を指定すると、Combat テストのみが実行されます
   • 特定の機能を開発中の場合に便利です

3. テストの実行時間を監視する - 適切なタイムアウトを設定します

   • EditMode：通常 1～3 分
   • PlayMode：通常 5～15 分
   • テスト数に応じてタイムアウトを調整します

4. Unity のバージョン互換性を確認する - Editor がプロジェクトのバージョンと一致していることを確認します

   • バージョンが一致しないと、テストが失敗することがあります
   • バージョンによってテスト結果に一貫性がない場合があります

5. 結果をすぐに解析する - 手動での確認を待たないでください

   • 自動解析により、問題をより早く検出できます
   • 対応に役立つファイル名と行番号が提示されます

6. 失敗パターンを分析する - よくある原因を探します

   • 類似した失敗は、システム全体に影響する問題を示している場合があります
   • 個々の症状ではなく、根本原因を修正します

7. テスト結果を保存する - デバッグ用に XML ファイルを保持します

   • 結果には完全なスタックトレースが含まれます
   • テスト実行結果の比較に役立ちます

8. 実行時間の長いテストに対応する - バックグラウンドで実行します

   • BashOutput ツールで進行状況を監視します
   • ユーザーに状況を報告します

リソース

scripts/find-unity-editor.js

クロスプラットフォーム対応の Unity Editor パス検出スクリプトです。Windows、macOS、Linux の既定のインストールディレクトリを自動的に検索して、インストール済みのすべての Unity バージョンを検出し、最新バージョンまたは指定されたバージョンを返します。

使用方法：

# Find latest Unity version
node scripts/find-unity-editor.js --json

# Find specific version
node scripts/find-unity-editor.js --version 2021.3.15f1 --json

出力：Unity Editor のパス、バージョン、プラットフォーム、および利用可能なすべてのバージョンを含む JSON です。

scripts/parse-test-results.js

Unity Test Framework の出力用 NUnit XML 結果パーサーです。XML の結果からテストの統計情報、失敗の詳細、スタックトレース、およびファイルの場所を抽出します。

使用方法：

# Parse test results with JSON output
node scripts/parse-test-results.js TestResults.xml --json

# Parse with formatted console output
node scripts/parse-test-results.js TestResults.xml

出力：テストの概要、ファイルパスと行番号を含む失敗の詳細、およびすべてのテストの一覧を含む JSON です。

references/test-patterns.json

Unity のテストパターン、NUnit のアサーション、一般的な失敗パターン、ベストプラクティスをまとめたデータベースです。以下が含まれます。

• NUnit アサーションのリファレンス（等価性、コレクション、例外、Unity 固有）
• 正規表現マッチングによる一般的な失敗パターン
• 失敗の分類と根本原因の分析
• コード例付きの解決策テンプレート
• EditMode と PlayMode の使い分けに関するガイダンス
• Unity 固有のテストパターン（コルーチン、シーン、プレハブ、物理演算）
• テストのベストプラクティス

使用方法：テストの失敗を分析する際にこのファイルを読み込み、失敗メッセージをパターンと照合して、修正案を生成します。