uw-unity-test-runner

Unity Test Runner

Generate NUnit tests mapped from GDD Gherkin scenarios.

Before You Start

1. Read docs/GDD.md for Gherkin scenarios (Given/When/Then) to convert into tests.
2. Ensure a Tests.asmdef exists for the feature — create with uw-unity-feature-scaffold if needed.
3. Read docs/CODING_STANDARDS.md for async patterns (Awaitable + CancellationToken) used in PlayMode tests.
4. Read docs/NAMING_CONVENTIONS.md for test class and file naming.
5. Check docs/ProjectConfig.yaml -> mcp.unity_mcp — if true, use run_tests / get_test_job to execute tests. Otherwise, instruct the user to run via Unity Editor (Window -> General -> Test Runner).

Test Types

Type	Location	When to Use	Runner
EditMode	Tests/EditMode/	Pure logic — no MonoBehaviour lifecycle, no scene required	[Test] with NUnit
PlayMode	Tests/PlayMode/	Needs Awake/Start/Update, scene loading, physics, or coroutines	[UnityTest] + IEnumerator

Default to EditMode whenever possible — they're faster, more reliable, and easier to debug. Only use PlayMode when the code under test depends on Unity's runtime lifecycle.

Gherkin to Test Mapping

Each Gherkin scenario from the GDD becomes one test method. The Given/When/Then structure maps directly to Arrange/Act/Assert:

Scenario: Player takes damage
  Given a player with 100 health
  When the player takes 30 damage
  Then the player health should be 70

using NUnit.Framework;

namespace {RootNamespace}.{FeatureName}.Tests
{
    [TestFixture]
    public class HealthSystemTests
    {
        [Test]
        public void TakeDamage_WithFullHealth_ReducesHealthByDamageAmount()
        {
            // Given
            var health = new HealthSystem(maxHealth: 100);

            // When
            health.TakeDamage(30);

            // Then
            Assert.AreEqual(70, health.CurrentHealth);
        }
    }
}