Skip to content

t1k:unity:testing:workflow

FieldValue
Moduletesting
Version4.45.4
Efforthigh
Tools—

Keywords: ci without unity licence, dotnet test without unity, InitTestScene, PlayMode tests never start, playModeStartScene, test runner, testing, tests did not start within timeout, unity free tier ci, UNITY_SERIAL, workflow

/t1k:unity:testing:workflow

Complete workflow for Unity test configuration, debugging test failures, and analyzing test results.

Two design-time calls this skill assumes are already made. (1) Where the tests belong — a module’s test asmdef ships with the module (Runtime/ + Editor/ + Tests/EditMode/ as one unit), never in a sibling’s assembly or a project-global bucket; see code-conventions.md § “Modular Boundaries” for the rule and t1k-unity-base-project-structure § Layer 3 for the Unity layout. (2) Where the logic belongs — Tier-2/Tier-3 game rules live off the MonoBehaviour per t1k-game-arch, so a test needs no scene and no Play mode. DOTS carve-out: an ISystem is already the logic layer and is already headless-testable via DOTSTestBase — never extract one into a plain class.

  • Setting up new Unity test assemblies
  • Tests don’t appear in Unity Test Runner
  • Debugging test compilation errors
  • Analyzing test failures
  • Running tests in batch mode / CI
  • Before opening the Unity Editor at all — compile first (see the section below)
  • Finding and parsing TestResults.xml
  • Troubleshooting test discovery issues

Minimum required fields in .asmdef:

{
"name": "YourPackage.Tests",
"references": ["YourMainAssembly", "UnityEngine.TestRunner", "UnityEditor.TestRunner"],
"includePlatforms": ["Editor"],
"overrideReferences": true,
"precompiledReferences": ["nunit.framework.dll"],
"autoReferenced": true,
"defineConstraints": ["UNITY_INCLUDE_TESTS"]
}

→ See references/test-assembly-config.md for full .asmdef template, folder structure, meta files, and test code patterns.

Tests don’t appear? Verify in order:

  1. UnityEngine.TestRunner in references
  2. UnityEditor.TestRunner in references
  3. "includePlatforms": ["Editor"]
  4. "overrideReferences": true
  5. "precompiledReferences": ["nunit.framework.dll"]
  6. "defineConstraints": ["UNITY_INCLUDE_TESTS"]
  7. Test class public + [TestFixture]
  8. Test methods public + [Test]
  9. .meta files exist for all test files
  10. Cache cleared: Assets → Reimport All

→ See references/test-debugging-guide.md for compilation errors, cache clearing, assertion failures, and systematic debug approach.

⛔ Compile FIRST — never open the Editor or run tests on a red tree

Section titled “⛔ Compile FIRST — never open the Editor or run tests on a red tree”

Before you open the Unity Editor, and before you run any test suite: compile, read the FULL error set, and fix every issue. Only then open Unity or run tests.

This is not a preference — opening a GUI Editor or launching a suite against uncompiled changes wastes the single most expensive resource on a Unity project, the domain-reload round trip, and it produces results you cannot trust:

  • A failed compile leaves the PREVIOUS assemblies in place. Unity keeps running the last good DLLs, so the Editor opens “fine” and the suite runs green against code you did not write. The mtime of the DLL does not advance, which is indistinguishable from “no compile was needed” — see t1k-unity-dots-core-tester.md § “Compile-verification gotchas” (“A stable mtime is AMBIGUOUS”).
  • A test run started on a red tree either dies on launch or silently drops the broken assemblies from discovery. The summary still reads green, just over far fewer tests. Compare the discovered count against the previous known run, every time.
  • The Editor is a mutex (t1k-unity-editor-cli SKILL.md § “Editor mutex: obligations that stay”). Opening it to discover a compile error you could have found headlessly in minutes blocks every other session on the machine.
Terminal window
# 0. Do not run this against a project whose GUI editor is open — two Unity processes on
# one project fight over Temp/UnityLockfile and Library/. Close the editor (ask the user;
# never kill it yourself — see `unity-forbidden-operations.md`) or run against a separate
# checkout.
# 1. COMPILE FIRST — headless, no Editor needed. COMPILE-ONLY: no -runTests. A test-runner
# invocation here defeats the gate — see references/headless-compile-verification.md.
# EVERY headless launch goes through unity-batch-gate.sh — a headless Unity run costs
# ~5-7 GB and N agents on N worktrees have no machine-wide limit without it
# (references/batch-mode-guide.md § "The machine-wide batch gate").
source .claude/scripts/unity-batch-gate.sh
UED=~/Unity/Hub/Editor/<version>/Editor/Unity
unity_batch_gate_run "$UED" -batchmode -nographics -quit -accept-apiupdate -acceptSoftwareTermsForThisRunOnly \
-projectPath "$PWD" -logFile "$PWD/Logs/compile.log"
# 2. READ THE FULL ERROR SET — unfiltered. DOTS source-gen emits EA####/DC####,
# Burst emits BC####, MemoryPack emits MEMPACK###. `grep "error CS"` misses all of them.
grep -E 'error (CS|EA|DC|BC|MEMPACK)[0-9]+' Logs/compile.log | sort -u
# 3. Assembly count is the cheapest failure detector — a shortfall means DLLs failed to build
ls Library/ScriptAssemblies/*.dll | wc -l # compare against the project's known-healthy count
# 4. FIX EVERY ERROR IN ONE BATCH, then re-run step 1. Repeat until the error set is EMPTY.
# A per-file error read lies: Roslyn hides member errors under an erroneous base class.
# Accept a test file only on a zero-error WHOLE build (references/headless-compile-verification.md).
# 5. ONLY NOW open the Editor / hand it to a human to play — and only THEN run the test suite,
# per `references/batch-mode-guide.md`.

Fix them all in one batch, not one at a time. Errors surface in layers, so the loop is collect-all → fix-all → re-run, never fix-one-and-recompile (ai-velocity-batch-compile-unity.md).

For the full batchmode compile-only loop (the -quit variant, why the GUI can SIGSEGV on 6000.5, why error counts rise as you fix), see references/headless-compile-verification.md. The section above is the gate the test skill enforces; that reference is the complete mechanics.

Checking whether Unity is running — the check that lies

Section titled “Checking whether Unity is running — the check that lies”
Terminal window
ps -eo comm --no-headers | grep -E '^Unity Main' # correct
ps -eo comm --no-headers | grep -qx Unity # WRONG — can never match
pgrep -af "Unity.*<project>" # correct — but read the output, don't test it

ps -eo comm truncates at 15 characters, so Unity reports as Unity Main Thre. An exact match on Unity never fires, and a live, healthy run reads as a dead one. This produced a phantom “something is killing our batchmode runs” blocker that survived a whole session (2026-08-27/28) before anyone checked the check. A batchmode log is also legitimately quiet during the ~4-minute asset import, so a stalled-looking ~11 KB log plus a false “no process” reading is very convincing and completely wrong. Confirm the log is still GROWING before concluding anything died. For a -runTests invocation specifically, also confirm TestResults*.xml is absent — a compile-only -quit pass never writes one, so that half of the check is vacuous there.

pgrep -f "Unity.*<project>" run inside a scripted wrapper (e.g. bash -c "... | pgrep -f ...") can self-match its own command line and falsely report a live process even when none exists. t1k-unity-editor-cli/references/incident-history.md’s sanctioned form is pgrep -af "Unity.*<Project>" — the -a prints the full command line so a human can visually rule out the self-match. Do not test its bare exit code or line count in an automated conditional without first excluding the pgrep/grep line itself; read the output.

Terminal window
source .claude/scripts/unity-batch-gate.sh # every headless launch goes through the machine-wide gate
unity_batch_gate_run_tests "$(unity_batch_gate_resolve /path/to/project)" /path/to/results.xml \
-projectPath /path/to/project \
-testPlatform EditMode \
-logFile /path/to/test.log
# exit 0 = ran and passed | 2 = Unity reported failures | 75 = gate refused, retry | 77 = empty run
# (stderr says no-results | zero-tests | all-skipped) -- 77 is NOT a pass
Terminal window
# Analyze failures
grep -B 5 'result="Failed"' TestResults.xml
grep 'Expected:' TestResults.xml

→ See references/batch-mode-guide.md for CI integration, XML format, coverage limitations. → No licence, no editor: a subset of EditMode fixtures (source-text / JSON / asmdef / pure-logic, no Unity type) can run in CI with plain dotnet test — the reference lane is ci/unity-free-tests/run.sh in The1Studio/unity-dots-library. It is a strict subset; a licensed editor still needs UNITY_SERIAL + UNITY_EMAIL + UNITY_PASSWORD (a .ulf cannot activate 6000.5, and login-only fails with Found 0 free entitlements / exit 198). Full scope and the measured licensing facts: references/ci-licence-free-lane.md.

New project: keep Unity-free tests Unity-free so they stay in the licence-free lane (references/ci-licence-free-lane.md); setup defaults and visual-verification layers: t1k-unity-base-project-structure/references/fast-iteration-defaults.md.

Is this test engine-free? (Tier-2 / Tier-3 — NOT DOTS)

Section titled “Is this test engine-free? (Tier-2 / Tier-3 — NOT DOTS)”

A test over extracted game logic (t1k-game-arch’s Domain layer) should satisfy all four. Failing any one means the logic is still welded to the engine and the test will pay the domain-reload tax:

  1. Subject built with new — no AddComponent, no GameObject, no ScriptableObject.CreateInstance
  2. [Test], never [UnityTest]/yield return null, never Play mode
  3. Time / randomness / input passed in (Advance(float dt), injected seed, input struct) — never Time.deltaTime, Random.value, or Input.* read inside the logic
  4. No reflection needed to reach the behaviour under test

Not a checklist for DOTS. An ISystem is the logic layer already; test it via DOTSTestBase (t1k-unity-dots-testing-unit-testing), which is headless and Play-mode-free by construction.

Don’t over-apply it either — a view/glue component that just sets a sprite or forwards a click has no rules to extract, and a bake-only authoring MonoBehaviour carries none either. The question is whether there’s an assertion worth writing that has nothing to do with the engine.

  • Missing includePlatforms: ["Editor"] — most common cause of tests not appearing
  • Missing UnityEngine.TestRunner or UnityEditor.TestRunner reference
  • Test class or method not public
  • .meta files missing (causes import issues)
  • Not clearing cache after config changes

Full detail: references/incident-history.md. Read it before acting on this topic.

  • A suite that reads a git-excluded folder fails only in a worktree. Check the failure list for tests that pass in the main clone, then symlink the folder in rather than copying it, and say in the report which tests ran against a symlinked fixture. Do not “fix” them by skipping.
  • t1k-unity-dots-testing-unit-testing — DOTS ECS test patterns
  • t1k-unity-testing-code-coverage — Code coverage reports (Editor GUI only, not batch mode)
  • t1k-game-arch (core) — the Domain/Application/Presentation split that makes the checklist above pass; names the root cause of the focus-flaky Update() gotcha (logic taking dt as a parameter is never focus-flaky and never needs reflection)
  • t1k-unity-base-project-structure — where a module’s Tests/EditMode/ asmdef lives
FileContents
references/test-assembly-config.mdFull .asmdef template, folder structure, meta files, test code patterns
references/test-debugging-guide.mdDiscovery checklist, cache clearing, compilation errors, systematic debug
references/batch-mode-guide.mdCLI execution, CI integration, XML format, coverage limitation, the machine-wide batch gate
references/ci-licence-free-lane.mdRunning a CI test lane with NO licence / NO editor (strict subset), and the measured licensing facts (.ulf cannot activate 6000.5; serial still required for the rest)
references/headless-compile-verification.mdBatchmode compile loop for migrations/refactors — full error set in one pass, why the 6000.5 GUI can SIGSEGV, why error counts rise as you fix
references/parallel-worktree-testing.mdRunning tests from several git worktrees at once — Library cache cost, license-seat caveat, the machine-wide batch gate, the t1k unity per-worktree binding
references/mutation-rerun-targeting.mdMutation re-runs: derive a targeted fixture manifest from the mutated files, never run the full suite per mutant; the full suite runs once at the root gate
references/launch-economics.mdWhat a Unity launch costs (measured floor and cold-import tail), batching one launch per verification round, warm Library seeding (reflink, never touch the Bee cache), T0 before the gate, two-phase verifier, commit before long waits, a sentinel is not a result (judge the results XML), lane-copy Library reconciliation