MaarkssDN/Birthub-360 / .agents/skills/unity-test-framework
unity-test-framework
UnverifiedUse whenever C# code in a Unity game-engine project needs tests that use the Unity runtime or editor: Unity Test Framework EditMode vs PlayMode tests, [Test] and [UnityTest], assembly definitions, the Test Runner window, batch-mode command-line runs and CI. Not the ThrowTheSwitch C library.
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
docs.unity3d.com/Packages/com.unity.test-framework@latest.
It is distinct from the ThrowTheSwitch Unity C testing library at
throwtheswitch.org/unity (a
single-C-file unit-test framework for bare-metal MCUs). The two tools share
only a name; they have unrelated origins, APIs, and consumers. For the C
unit-test library, see the sibling skill unity-test-framework-c in the
qa-embedded plugin.
UTF is built on NUnit 3.5 and supports both Edit Mode and Play Mode across Standalone, Android, and iOS target platforms (per the package overview).
Versioning. UTF is currently v1.8; the stable doc links below pin to the v1.4 manual snapshot for durable URLs. Both describe the same package.
Composes with:
platform-cert-overview-referencefor what category of test each Unity test belongs to (functional / performance / etc.), and for cert-gated requirements UTF tests should cover (XR-001 Title Stability, XR-074 Service Loss, XR-115 Controller add / remove).multiplayer-state-machine-coverageandgameplay-recording-replayfor 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
UTF "is shipped with the Unity Editor and should be automatically included in
any project created with Unity 2019.2 or later" (per the package overview). For
manual install, open Package Manager → + → "Add package by name…" →
com.unity.test-framework.
The Test Runner window is at Window → General → Test Runner (may be Window → Test Runner depending on Editor version).
EditMode tests
Per the Edit Mode vs Play Mode tests page, Edit Mode tests "are only run in the Unity Editor and have access to the Editor code in addition to the game code".
Layout (two options):
- Editor folder (legacy): place tests under any folder named
Editor/. Unity auto-scopes them to the Editor platform. - Assembly definition (recommended): create an
.asmdefwith"includePlatforms": ["Editor"].
Minimal example:
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.
}
}
}
The docs recommend the NUnit Test attribute rather than UnityTest unless
you need to yield special instructions in Edit Mode, or skip a frame / wait for
an amount of time in Play Mode.
PlayMode tests
PlayMode tests "execute as coroutines within the game runtime and can run standalone in a Player or within the Editor". Assembly definition:
{
"name": "MyGame.Tests.PlayMode",
"references": ["MyGame.Runtime"],
"optionalUnityReferences": ["TestAssemblies"],
"includePlatforms": []
}
Per the edit-mode-vs-play-mode docs, the .asmdef must reference the code
under test ("references": ["NewAssembly"]), optionally include
"optionalUnityReferences": ["TestAssemblies"], and leave
"includePlatforms": [] empty to allow multiple target platforms.
Minimal example:
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");
}
}
}
The [UnityTest] attribute, returning IEnumerator, lets the test yield
frames (yield return null), seconds (yield return new WaitForSeconds(2f)),
or custom yield instructions - necessary for any frame-driven behaviour.
Attributes
The common attributes are [Test] (synchronous NUnit), [UnityTest]
(coroutine, yields frames/seconds), [SetUp] / [TearDown],
[OneTimeSetUp] / [OneTimeTearDown], [Category("Smoke")] (CLI-selectable),
and [UnityPlatform(...)]. The full cheatsheet with sources and the
ValueSource parameterisation note is in
references/attributes.md.
NUnit assertion APIs
UTF is built on NUnit 3.5, so the full NUnit 3 assertion model applies -
Assert.AreEqual, Assert.Throws<T>(() => ...),
Assert.That(actual, Is.EqualTo(expected).Within(0.01f)), etc. Prefer the
NUnit Test attribute over UnityTest unless you need to yield special
instructions.
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)
Invoke Unity in batch mode and treat the -testResults XML as the source of
truth (Unity has no common exit-code definition):
Unity \
-batchmode \
-projectPath "$PWD" \
-runTests \
-testPlatform PlayMode \
-testResults artifacts/playmode-results.xml \
-testCategory "Smoke" \
-logFile artifacts/unity.log
The full batch-mode flag table (-testFilter, -testPlatform,
-assemblyNames, ordering / retry flags), the Windows invocation, and the
exit-code caveat are in references/cli.md.
Parsing results
The -testResults XML is NUnit 3 result format. Surface result="Failed"
at the <test-run> level for the overall verdict, then enumerate
<test-case result="Failed"> for per-test detail; nunit-junit-xml
converters exist for JUnit consumers. The full schema example is in
references/results-and-ci.md.
CI integration
Run UTF in CI via game-ci/unity-test-runner (or the bare batch-mode CLI),
upload the -testResults XML as an artifact, and cache the Library/ folder
across runs - Unity re-imports all assets without it, adding 5 - 15 min per
run. A complete GitHub Actions workflow is in
references/results-and-ci.md.
Anti-patterns
| Anti-pattern | Why it fails | Fix |
|---|---|---|
Using [UnityTest] everywhere | Slower than [Test] because each test enters play mode | Use [Test] unless you need to yield (per the edit-mode-vs-play-mode docs) |
Forgetting optionalUnityReferences: ["TestAssemblies"] | Test assembly isn't picked up by Test Runner | Add it per the PlayMode asmdef block above |
| Test asmdef references production asmdef but production has no public types | Tests can't compile | Use InternalsVisibleTo on production asmdef or expose minimal public surface |
Not cleaning up GameObjects between EditMode tests | Cross-test contamination | [TearDown] Object.DestroyImmediate(go) on every fixture |
| Trusting Unity process exit code in CI | No common definition for exit codes | Parse -testResults XML in CI |
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
Known constraints (per the v1.4 manual index):
- No WSA platform support for
UnityTest- Windows Store Apps cannot run[UnityTest]coroutine-style tests. - Parameterised tests unsupported (except
ValueSource) - NUnit[TestCase],[TestCaseSource]have historical caveats in UTF. [Repeat]attribute incompatibility - listed as a known limitation.- Nested test fixtures cannot run from the Editor UI.
[Retry]attribute causesInvalidCastExceptionin PlayMode tests.
Other practical limitations:
- Asset Database in PlayMode is sandboxed. PlayMode tests cannot freely create / mutate assets the way EditMode tests can.
- Coverage requires the separate
com.unity.testtools.codecoveragepackage; not included by default. - License gating on CI - Unity batch-mode CI requires either an activated
Personal/Plus license seat or a manual
.ulflicense file; consult Unity's documentation for the current activation flow before standing up CI. Keep the seat credentials or the.ulfcontents in the CI secret store and inject them as environment variables; never write them into a workflow file or a logged command line. - No public common exit-code definition (per the command-line reference); parse XML, don't rely on exit code.
- EditMode test that enters PlayMode is supported ("Edit Mode tests can control entering and exiting Play Mode from your test") but cross-mode tests are notoriously flaky; prefer keeping the two modes' tests separate.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |