初めてのUnity Test Framework ― 基礎から動かし方まで完全ガイド

2025年5月1日

1. Unity Test Frameworkとは？

Unity Test Framework（旧称 Test Runner）は、Edit モードと Play モードの両方でテストを実行できる Unity Editor 内蔵ツールです。NUnit をベースに Unity 固有のコルーチンやフレームループを扱う機能を拡張しています (Unity – Manual: Testing your code).

2. なぜテストが必要か？

品質保証：コード変更による不具合を即座に検出し、手動テストやユーザー報告に頼る必要を減らします。
効率化：大規模化したプロジェクトでは、どこで壊れたかを自動テストで特定でき、開発速度を維持できます (ユニットテスト – Unity マニュアル).

3. Edit モードテスト vs Play モードテスト

Unity Test Framework は、テストの実行環境に応じて以下の２種類を区別します (Unity – Manual: Edit mode and Play mode tests).

Edit モードテスト

実行環境：Unity Editor 内のみ
アクセス可能 API：UnityEditor と UnityEngine 名前空間
コルーチン：不可（[UnityTest] でも IEnumerator は使用不可）
用途：エディター拡張や小規模ユーティリティの単体テストに最適

Play モードテスト

実行環境：Editor またはビルド済みプレイヤー（Standalone/Android/iOS 等）
コルーチン：[UnityTest] 属性で IEnumerator を使ったフレーム待機が可能
用途：実際のランタイム挙動、フレーム単位の処理、ユーザー入力検証などに利用

4. Unity Test Framework ウィンドウの起動方法

Unity メニューから Window > General > Test Runner を選択すると、Test Runner ウィンドウが開きます (Unity Test Runner – Unity マニュアル).
開いたウィンドウは、内部的には旧「Test Runner」ですが、これが Unity Test Framework ウィンドウです

5. テストアセンブリの作成

Test Runner ウィンドウ上部の Create a new Test Assembly Folder ボタンをクリック
自動で Assets/Tests フォルダと .asmdef（アセンブリ定義ファイル）、サンプルテストスクリプトが生成されます (Unity – Manual: Get started with Unity Test Framework).

6. テストコードの記述

6.1 同期テスト（`[Test]`）

using NUnit.Framework;

public class CalculatorTests
{
    [Test]
    public void Add_ReturnsCorrectSum()
    {
        var calc = new Calculator();
        Assert.That(calc.Add(2, 3), Is.EqualTo(5));
    }
}

基本的な単体テスト。同期的に処理を実行してすぐアサートします (Unity – Manual: Testing your code).

6.2 非同期テスト（`[UnityTest]`）

using UnityEngine.TestTools;
using NUnit.Framework;
using System.Collections;

public class CoroutineTests
{
    [UnityTest]
    public IEnumerator WaitOneFrame_Succeeds()
    {
        yield return null;  // 次フレームへ待機
        Assert.That(true, Is.True);
    }
}

コルーチンを使い、フレーム単位の待機や Unity の Instruction を扱えます (Unity – Manual: Testing your code).

7. テストの実行方法

7.1 Test Runner ウィンドウ

Edit Mode／Play Mode タブで実行したいテストを選び、Run Selected をクリック (Unity Test Runner – Unity マニュアル).

7.2 コマンドライン

Unity -batchmode -runTests -projectPath "<プロジェクトパス>" -testPlatform EditMode

-testPlatform に EditMode／PlayMode を指定
-assemblyNames や -testCategory で絞り込み可能 (Unity – Manual: Command-line reference).

7.3 コード実行（TestRunner API）

using UnityEngine.TestTools.TestRunner.Api;

var api = ScriptableObject.CreateInstance<TestRunnerApi>();
api.Execute(new ExecutionSettings { /* フィルタ設定など */ });

プログラムからテスト実行し、結果を取得できます (Unity – Manual: Testing your code).

8. チュートリアル：Calculatorクラスのテスト

8.1 準備

Assets/Scripts/Calculator.cs を以下のように作成：

public class Calculator
{
    public int Add(int a, int b) => a + b;
}

8.2 テストアセンブリとスクリプトの生成

Test Runner の Create a new Test Assembly Folder から自動生成 (Unity – Manual: Get started with Unity Test Framework).

8.3 テストコードの実装

Assets/Tests/CalculatorTests.cs を次のように編集：

using NUnit.Framework;

public class CalculatorTests
{
    [Test]
    public void Add_ReturnsSumOfTwoNumbers()
    {
        var calc = new Calculator();
        Assert.That(calc.Add(3, 4), Is.EqualTo(7));
    }
}

8.4 テスト実行＆確認

Test Runner の Edit Mode タブで Run Selected → 緑チェックで合格
IDE（Visual Studio 等）のテストエクスプローラーでも確認可能

9. よくあるトラブルシューティング

問題	原因例	対処方法
テストが一覧に表示されない	テストスクリプトが `.asmdef` 配下にない	`Assets/Tests` フォルダにスクリプトと `.asmdef` を配置
`[UnityTest]` テストが実行されない	`[Test]` 属性を使っている	`[UnityTest]` 属性に変更し `IEnumerator` を返す
CLI 実行でテストが走らない	引数の `-projectPath` や `-testPlatform` ミス	コマンド引数を正しく指定
API 実行で例外が発生	`ExecutionSettings` の設定不備	`assemblyNames` やフィルタを見直す