📝 Lesson 5.2: Debugging and the Unity Test Framework

Debugging Mindset

Debugging is a science, not luck: form a hypothesis about what's wrong, gather evidence, and narrow it down. Unity gives you tools for each step — the Console for messages, Gizmos for seeing invisible logic, and a debugger for freezing time and inspecting state.

💡 The most common Unity bug isn't in your logic — it's a reference that's null, an event function that's misspelled (Lesson 1.2), or code running in the wrong order. Before suspecting complex logic, check the simple things: Is the reference assigned in the Inspector? Is the object active? Did Awake run before this?

Logging Well

The Debug class writes to the Console. Three severity levels help you scan output — and errors/warnings can be filtered separately:

Debug.Log("Player spawned");                     // white — info
Debug.LogWarning("Health below 10%");            // yellow — attention
Debug.LogError("Missing weapon reference!");     // red — a real problem

// Pass 'this' (or any Object) as a second argument: clicking the message
// pings that object in the Hierarchy — invaluable for "which one broke?".
Debug.LogError("Target not assigned", this);

Visual Debugging: Gizmos

Some bugs are spatial — a detection radius that's wrong, a ray pointing the wrong way, a patrol path off by a bit. Numbers in the Console won't reveal these; drawing them will. Unity offers two visual tools:

using UnityEngine;

public class EnemyVision : MonoBehaviour
{
    [SerializeField] private float viewDistance = 10f;
    [SerializeField] private float detectRadius = 3f;

    void Update()
    {
        // Draw the forward view ray each frame (red), visible in the Scene view.
        Debug.DrawRay(transform.position, transform.forward * viewDistance, Color.red);
    }

    // Gizmos draw in the editor even when not playing — great for tuning.
    void OnDrawGizmosSelected()
    {
        Gizmos.color = Color.yellow;
        Gizmos.DrawWireSphere(transform.position, detectRadius);   // see the detection range
    }
}

Breakpoints & Common Bugs

Logging shows values after the fact; a breakpoint freezes the game at a line so you can inspect everything — variable values, the call stack, and step through line by line. Attach your IDE (Visual Studio / Rider) to Unity ("Attach to Unity"/"Play"), set a breakpoint by clicking the gutter, and trigger the code.

Most Unity bugs fall into a few recognizable buckets. Knowing the pattern speeds the fix:

The Unity Test Framework

Debugging fixes a bug once. A test makes sure it stays fixed. The Unity Test Framework (UTF) builds on NUnit — the same framework from the Intermediate C# course — and runs from Window → General → Test Runner. There are two kinds:

An Edit Mode test is a plain NUnit test — perfect for pure C# logic. It follows the Arrange–Act–Assert pattern you learned before:

using NUnit.Framework;

public class ScoreRulesTests
{
    [Test]
    public void ComboMultiplier_DoublesScore_AtThreeHits()
    {
        // Arrange
        var rules = new ScoreRules();

        // Act
        int score = rules.Points(baseValue: 100, comboHits: 3);

        // Assert
        Assert.AreEqual(200, score);
    }
}

A Play Mode test runs in a real scene and can span frames using [UnityTest] with an IEnumerator (the coroutine shape from Lesson 3.3) — so you can yield and check results after time passes:

using System.Collections;
using UnityEngine;
using UnityEngine.TestTools;   // [UnityTest]
using NUnit.Framework;

public class MovementTests
{
    [UnityTest]
    public IEnumerator Player_MovesForward_OverTime()
    {
        // Arrange: build a live object with the component under test.
        var go = new GameObject();
        var mover = go.AddComponent<PlayerMover>();
        Vector3 start = go.transform.position;

        // Act: let a few frames pass.
        yield return new WaitForSeconds(0.5f);

        // Assert: it actually moved.
        Assert.Greater(go.transform.position.z, start.z);
    }
}

Writing Testable Code

Here's the payoff of good architecture: logic that doesn't depend on Unity is trivial to test. A scoring rule buried inside a MonoBehaviour needs a running scene to test; the same rule in a plain C# class can be tested in milliseconds, in Edit Mode.

// ❌ Hard to test: logic tangled with MonoBehaviour + Unity state.
public class ScoreManager : MonoBehaviour
{
    private int score;
    void Update()
    {
        if (Input.GetKeyDown(KeyCode.Space))
            score += 100 * (comboHits >= 3 ? 2 : 1);   // rule hidden in Update
    }
}

// ✅ Easy to test: the RULE is a pure class; the MonoBehaviour just calls it.
public class ScoreRules   // no MonoBehaviour — plain C#, unit-testable
{
    public int Points(int baseValue, int comboHits)
        => baseValue * (comboHits >= 3 ? 2 : 1);
}

public class ScoreManager : MonoBehaviour
{
    private readonly ScoreRules rules = new();
    private int score;

    public void RegisterHit(int comboHits) => score += rules.Points(100, comboHits);
}

💡 What to test first: your logic — scoring, inventory limits, damage formulas, save/load round-trips, state-machine transitions (Lesson 4.1). These are where subtle bugs hide and where a fast Edit Mode test pays off every time you refactor. You don't need 100% coverage; test the rules that would hurt if they broke.

Exercise & Quiz

public class ScoreRules
{
    // TODO: double the base value when comboHits is 3 or more.
    public int Points(int baseValue, int comboHits) => baseValue;
}

using NUnit.Framework;

public class ScoreRulesTests
{
    // TODO: [Test] methods for 1 hit, 3 hits, 5 hits using Assert.AreEqual.
}

public class ScoreRules
{
    public int Points(int baseValue, int comboHits)
        => baseValue * (comboHits >= 3 ? 2 : 1);
}

using NUnit.Framework;

public class ScoreRulesTests
{
    [Test]
    public void OneHit_NoBonus()
    {
        var rules = new ScoreRules();
        Assert.AreEqual(100, rules.Points(100, 1));
    }

    [Test]
    public void ThreeHits_Doubled()
    {
        var rules = new ScoreRules();
        Assert.AreEqual(200, rules.Points(100, 3));
    }

    [Test]
    public void FiveHits_Doubled()
    {
        var rules = new ScoreRules();
        Assert.AreEqual(200, rules.Points(100, 5));
    }
}

Summary

📚 Additional Resources

• Scripting Reference — Debug (Log, DrawRay…)
• Scripting Reference — OnDrawGizmos
• Manual — Unity Test Framework
• Manual — Debugging C# code (breakpoints)

🚀 What's Next?

You can build fast, correct, well-tested Unity C#. Time to put it all together. Lesson 5.3, the Capstone Project, guides you through building a complete gameplay system — components, lifecycle, input, physics, data, events, managers, UI, save/load, and performance — everything from this course in one cohesive build.