unity-testing

Unity Test Framework

Test Framework Overview

The Unity Test Framework (UTF) is Unity's built-in testing solution, integrating a custom version of NUnit (based on NUnit 3.5) adapted for Unity. It enables testing C# code in Edit Mode, Play Mode, and on target platforms (Standalone, Android, iOS).

UTF extends NUnit with Unity-specific attributes ([UnityTest], [UnitySetUp], [UnityTearDown]) that support coroutines, yield instructions, and frame-based execution.

Key capabilities:

• Edit Mode tests for editor extensions and pure logic
• Play Mode tests for gameplay, physics, and coroutine-based code
• Standalone player test builds for platform-specific validation
• Command-line execution for CI/CD pipelines
• NUnit XML result output

Source: Unity Test Framework 2.0 Manual

---

Setup and Configuration

Installing the Test Framework

UTF ships with Unity by default. Open the Test Runner via Window > General > Test Runner.

Creating a Test Assembly

Test code must live in its own assembly definition (.asmdef) that references NUnit.

Create via Window > General > Test Runner (click Create a new Test Assembly Folder) or Assets > Create > Testing > Test Assembly Folder.

This creates a Tests folder with an .asmdef file preconfigured with references to:

• nunit.framework.dll
• UnityEngine.TestRunner
• UnityEditor.TestRunner (Edit Mode only)

Edit Mode Assembly Definition (.asmdef)

{
    "name": "Tests",
    "references": [
        "UnityEngine.TestRunner",
        "UnityEditor.TestRunner"
    ],
    "includePlatforms": ["Editor"],
    "defineConstraints": ["UNITY_INCLUDE_TESTS"],
    "autoReferenced": false
}

Play Mode Assembly Definition (.asmdef)

{
    "name": "Tests.PlayMode",
    "references": [
        "UnityEngine.TestRunner",
        "UnityEditor.TestRunner",
        "MyGameAssembly"
    ],
    "includePlatforms": [],
    "optionalUnityReferences": ["TestAssemblies"],
    "defineConstraints": ["UNITY_INCLUDE_TESTS"],
    "autoReferenced": false
}