git:20260724.d4db756 to git:20260728.1bce424

---

name: unity-test-framework

description: "Author and run the Unity game-engine Test Framework (`com.unity.test-framework`, currently v1.8). Distinct from the ThrowTheSwitch Unity C testing library at throwtheswitch.org/unity - the two tools share only a name. Covers package install via Package Manager, the EditMode vs PlayMode split, the [Test] / [UnityTest] / [SetUp] / [TearDown] / [UnityPlatform] attributes, assembly-definition setup (Editor folder vs asmdef with `includePlatforms` / `optionalUnityReferences: [TestAssemblies]`), Test Runner window, command-line batch invocation with `-runTests` / `-testPlatform` / `-testResults` / `-testFilter` / `-testCategory`, NUnit 3.5 assertion API, and CI integration. Use when the unit under test is C# Unity code that needs to exercise the Unity runtime or editor."

metadata:

keywords: "unity, unity3d, test-framework, utf, edit-mode, play-mode, nunit, csharp, game-engine"

---

# unity-test-framework

## Overview

**Disambiguation up front.** This skill covers the

**Unity game-engine Test Framework** - the official Unity package

`com.unity.test-framework` documented at

Composes with:

- `game-test-categories-reference`

for what category of test each Unity test belongs to (functional

/ performance / etc.).

- `platform-cert-overview-reference`

for cert-gated requirements UTF tests should cover (XR-001

Title Stability, XR-074 Service Loss, XR-115 Controller add /

remove).

- `multiplayer-state-machine-coverage`

and

`gameplay-recording-replay`

for state-machine and replay-driven test patterns inside UTF

PlayMode tests.

## When to use

- Unit under test is **C# Unity code** that needs the Unity

runtime (`MonoBehaviour`, `GameObject`, coroutines, scenes) or

editor (`AssetDatabase`, `EditorWindow`) APIs available.

- You want CI-runnable tests that integrate with Unity Cloud

Build, GitHub Actions, or other CI via Unity's batch-mode CLI.

- You need both isolated logic tests (EditMode) and integration

tests that exercise scene lifecycle (PlayMode) in one harness.

For C unit tests on the firmware side of a hybrid game build,

use `unity-test-framework-c` instead.

## Authoring

### Install via Package Manager

### EditMode tests

Per the

Layout (two options):

- **Assembly definition (recommended):** create an `.asmdef` with

`"includePlatforms": ["Editor"]`.

Minimal example:

```csharp

using NUnit.Framework;

using UnityEngine;

namespace MyGame.Tests.EditMode

{

public class HealthComponentTests

{

[Test]

public void Damage_DeductsCorrectAmount()

{

var go = new GameObject();

var health = go.AddComponent<HealthComponent>();

health.Initialize(maxHealth: 100);

health.ApplyDamage(35);

Assert.AreEqual(65, health.Current);

}

[TearDown]

public void Cleanup()

{

// EditMode tests must clean up created GameObjects;

// they don't auto-tear-down between cases.

}

}

}

```

### PlayMode tests

```json

{

"name": "MyGame.Tests.PlayMode",

"references": ["MyGame.Runtime"],

"optionalUnityReferences": ["TestAssemblies"],

"includePlatforms": []

}

```

Minimal example:

```csharp

using System.Collections;

using NUnit.Framework;

using UnityEngine;

using UnityEngine.TestTools;

namespace MyGame.Tests.PlayMode

{

public class EnemyAITests

{

[UnityTest]

public IEnumerator Enemy_PursuesPlayer_WithinRange()

{

var player = new GameObject("Player");

var enemy = Object.Instantiate(Resources.Load<GameObject>("Enemy"));

enemy.transform.position = new Vector3(10f, 0f, 0f);

yield return new WaitForSeconds(2f);

var distance = Vector3.Distance(player.transform.position,

enemy.transform.position);

Assert.Less(distance, 5f, "Enemy did not close on player");

}

}

}

```

### NUnit assertion APIs

## Running

### From the Test Runner window

**Window → General → Test Runner** (path may be Window → Test

Runner in older Editor versions). The window shows two tabs:

- **EditMode** - synchronous tests executed against the editor

domain.

- **PlayMode** - tests that enter and exit play mode for each

fixture.

Click **Run All**, **Run Selected**, or right-click a fixture →

**Run** to execute. Results display inline with stack traces on

failure.

### From the command line (batch mode)

```bash

Unity \

-batchmode \

-projectPath "$PWD" \

-runTests \

-testPlatform PlayMode \

-testResults artifacts/playmode-results.xml \

-testCategory "Smoke" \

-logFile artifacts/unity.log

```

## Parsing results

## CI integration

## Anti-patterns

| Anti-pattern | Why it fails | Fix |

|---|---|---|

| Not cleaning up `GameObject`s between EditMode tests | Cross-test contamination | `[TearDown]` `Object.DestroyImmediate(go)` on every fixture |

| Skipping the `Library/` cache | 5 - 15 min asset reimport per CI run | `actions/cache@v4` with the `Library/` path |

| Confusing this skill with ThrowTheSwitch Unity (C) | Different tool with the same name | See `unity-test-framework-c` |

## Limitations

- **Nested test fixtures cannot run from the Editor UI.**

Other practical limitations:

- **Coverage** requires the separate `com.unity.testtools.codecoverage`

package; not included by default.

- **License gating on CI** - Unity batch-mode CI requires either a

parse XML, don't rely on exit code.