🧪 Lesson 8.1: The Unity Test Framework — Edit & Play Mode Tests

Why Automated Tests

A test is a small program that exercises your code and asserts that the result is what you expect. If the assertion holds, the test passes; if not, it fails loudly and tells you exactly where. The payoff is not proving code correct once — it's proving it still correct after every change you make for the rest of the project's life.

That safety net is what makes the advanced work in this course sustainable. When you convert a system to a Burst job (Module 3), extract an interface for DI (Lesson 1.2), or split a monolith into assemblies (Lesson 1.1), tests tell you in seconds whether you preserved behaviour. Without them, "did I break anything?" is answered by hope.

NUnit, Edit Mode & Play Mode

The Unity Test Framework (UTF, package com.unity.test-framework, installed by default) is built on NUnit — the long-standing .NET testing library — with Unity-specific extensions layered on top. If you've written NUnit tests elsewhere, the attributes ([Test], [SetUp], Assert) are exactly the same. What Unity adds is the ability to run tests inside the engine, in one of two modes.

The rule of thumb: push as much logic as you can into plain C# that Edit Mode can test instantly, and reserve Play Mode for the genuinely runtime-dependent behaviour. A suite that's 90% Edit Mode runs in a blink; one that leans on Play Mode for everything crawls.

The Test Assembly

Back in Lesson 1.1 you learned that an .asmdef file carves your code into a separately compiled assembly. Tests live in their own assembly for two reasons: it keeps test code out of your shipping build, and it lets the assembly reference the Test Framework's engine and editor pieces that game code shouldn't.

Create a folder (say Assets/Tests/EditMode), then in the Project window use Create ▸ Testing ▸ Test Assembly Folder — or add an asmdef manually. A minimal Edit Mode test assembly definition looks like this:

{
    "name": "Game.Tests.EditMode",
    "references": [ "Game.Runtime" ],
    "includePlatforms": [ "Editor" ],
    "optionalUnityReferences": [ "TestAssemblies" ]
}

The magic entry is "TestAssemblies" under optionalUnityReferences — that flag is what tells Unity to reference UnityEngine.TestRunner and UnityEditor.TestRunner and to surface this assembly in the Test Runner. The references array points at the game assembly under test (here Game.Runtime), so your tests can see the classes they exercise. A Play Mode test assembly is the same minus the Editor-only platform restriction, so it can build into a player.

An Edit Mode Test

Here's a class under test — a pure scoring rule with no Unity dependencies at all, exactly the kind of logic Edit Mode tests love:

namespace Game.Runtime
{
    public static class Scoring
    {
        // Base points times a combo multiplier, clamped so a broken
        // combo can never subtract points.
        public static int ComboScore(int basePoints, int comboCount)
        {
            int multiplier = System.Math.Max(1, comboCount);
            return basePoints * multiplier;
        }
    }
}

And the test. Notice the structure: Arrange the inputs, Act by calling the method, Assert the result. That three-beat rhythm — AAA — keeps every test readable at a glance.

using NUnit.Framework;
using Game.Runtime;

public class ScoringTests
{
    [Test]
    public void ComboScore_MultipliesByComboCount()
    {
        // Arrange
        int basePoints = 100;
        int combo = 3;

        // Act
        int result = Scoring.ComboScore(basePoints, combo);

        // Assert
        Assert.AreEqual(300, result);
    }

    [Test]
    public void ComboScore_TreatsZeroComboAsSingle()
    {
        // A broken combo should still award the base, never zero.
        Assert.AreEqual(100, Scoring.ComboScore(100, 0));
    }
}

Two assertion styles exist and you'll see both. The classic Assert.AreEqual(expected, actual) is direct. NUnit also offers a fluent constraint model via Assert.That, which reads like a sentence and gives richer failure messages:

Assert.That(result, Is.EqualTo(300));
Assert.That(result, Is.GreaterThan(0).And.LessThanOrEqualTo(1000));
Assert.That(names, Does.Contain("boss").And.Not.Empty);

When a fixture needs shared setup, [SetUp] runs before each test and [TearDown] after — Unity re-creates the fixture per test so they never bleed state into one another:

public class InventoryTests
{
    private Inventory _inv;

    [SetUp]
    public void SetUp() => _inv = new Inventory(capacity: 4);

    [Test]
    public void Add_IncreasesCount()
    {
        _inv.Add(new Item("potion"));
        Assert.That(_inv.Count, Is.EqualTo(1));
    }

    [TearDown]
    public void TearDown() => _inv = null;
}

The Test Runner Window

Open Window ▸ General ▸ Test Runner. It has two tabs — PlayMode and EditMode — each showing a tree of your test assemblies, fixtures (classes), and individual tests. Green checks are passes, red crosses are failures. Select any node and Run Selected, or Run All. Click a failed test and the bottom pane shows the assertion that broke, the expected-vs-actual values, and a stack trace straight to the line. Because the Test Runner is a UI Toolkit window that doesn't screenshot cleanly, here it is reconstructed faithfully:

A Play Mode Test

Some behaviour only makes sense at runtime — a projectile that must travel for a few frames, a coroutine that resolves next frame, physics that needs to settle. For these you write a Play Mode test: mark it [UnityTest] and return IEnumerator, so you can yield to advance frames just like a coroutine.

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

public class ProjectileTests
{
    [UnityTest]
    public IEnumerator Projectile_MovesForwardOverTime()
    {
        // Arrange: spawn a fresh GameObject with the component under test.
        var go = new GameObject("proj");
        var proj = go.AddComponent<Projectile>();
        proj.Speed = 5f;
        Vector3 start = go.transform.position;

        // Act: let the engine run real frames.
        yield return null;               // one frame
        yield return new WaitForSeconds(0.2f);

        // Assert: it moved along +Z.
        Assert.That(go.transform.position.z, Is.GreaterThan(start.z));

        Object.Destroy(go);
    }
}

The key differences from Edit Mode: yield return null advances exactly one frame (running every Update), and yield return new WaitForSeconds(...) lets real time pass. Anything you spawn, you clean up — a Play Mode test shares the scene with the others in its run, so leaked GameObjects cause spooky failures downstream.

💡 [UnitySetUp] and [UnityTearDown]. Play Mode has coroutine-aware setup/teardown variants that also return IEnumerator, so you can yield while preparing (e.g. load a test scene with SceneManager.LoadSceneAsync and wait for it). Use them when plain synchronous [SetUp] isn't enough.

Writing Testable Code

The single biggest factor in whether tests are easy or agonising is the design of the code under test. Logic tangled directly into a MonoBehaviour that reaches for Time.deltaTime, Input, the network, and the file system is nearly impossible to test in isolation. Logic behind an interface, with its dependencies injected (Lesson 1.2), is trivial.

Consider a chest that grants a random reward. If it calls Random.Range directly, the test can't predict the result. Extract the randomness behind an interface and inject it:

public interface IRandomSource { int Range(int minInclusive, int maxExclusive); }

public class LootChest
{
    private readonly IRandomSource _rng;
    public LootChest(IRandomSource rng) => _rng = rng;   // injected

    public string Open(string[] table) => table[_rng.Range(0, table.Length)];
}

Now the test supplies a fake (a "stub") that returns a known value, making the outcome deterministic:

private class FixedRandom : IRandomSource
{
    private readonly int _value;
    public FixedRandom(int value) => _value = value;
    public int Range(int min, int max) => _value;
}

[Test]
public void Open_PicksEntryFromRandomIndex()
{
    var chest = new LootChest(new FixedRandom(2));
    string[] table = { "coin", "gem", "crown", "dust" };

    Assert.That(chest.Open(table), Is.EqualTo("crown"));   // index 2
}

This is why the architecture module comes first in the course and testing comes last: the DI, interfaces, and assembly boundaries you learned early are precisely what make the code you write testable now. The lesson generalises: separate decision-making logic from engine plumbing. Pure logic goes in plain C# classes (fast Edit Mode tests); the thin MonoBehaviour just wires inputs to that logic and needs only a light Play Mode test, if any.

Code Coverage

Once you have tests, a natural question is how much of your code they actually exercise. Unity's Code Coverage package (install via the Package Manager) instruments your assemblies and reports the percentage of lines and branches your tests touched, with an HTML report highlighting the untested lines in red.

Enable it (Window ▸ Analysis ▸ Code Coverage), tick "Generate HTML report", run your tests, and open the result. It's excellent for spotting whole systems that no test ever reaches. But treat the number as a flashlight, not a target: chasing 100% coverage rewards writing shallow tests for trivial getters while a single well-designed test of critical logic is worth more. Aim to cover the code where a bug would hurt — scoring, saves, economy, matchmaking — and don't sweat coverage on thin glue.

Hands-on Challenge

public class Health
{
    public int Current { get; private set; }
    public int Max { get; }
    public bool IsDead => Current <= 0;
    public Health(int max) { Max = max; Current = max; }
    public void Damage(int amount) => Current = System.Math.Max(0, Current - amount);
    public void Heal(int amount) => Current = System.Math.Min(Max, Current + amount);
}

using NUnit.Framework;
using Game.Runtime;

public class HealthTests
{
    private Health _hp;

    [SetUp]
    public void SetUp() => _hp = new Health(100);

    [Test]
    public void Damage_ReducesCurrent()
    {
        _hp.Damage(30);
        Assert.That(_hp.Current, Is.EqualTo(70));
    }

    [Test]
    public void Damage_ClampsAtZeroAndReportsDead()
    {
        _hp.Damage(999);
        Assert.That(_hp.Current, Is.EqualTo(0));
        Assert.That(_hp.IsDead, Is.True);
    }

    [Test]
    public void Heal_NeverExceedsMax()
    {
        _hp.Damage(10);
        _hp.Heal(50);
        Assert.That(_hp.Current, Is.EqualTo(100));
    }
}

Summary

🚀 What's Next?

Tests are only powerful if they run automatically, on every commit, not just when you remember. In Lesson 8.2: Automated & Cloud Builds (CI/CD) you'll drive Unity from the command line in batch mode, write a C# BuildScript that calls BuildPipeline.BuildPlayer, and wire a GitHub Actions pipeline that runs your new test suite and produces a build artifact — turning "I tested it on my machine" into "the server proves it on every push."