t1k:unity:testing:workflow
| Field | Value |
|---|---|
| Module | testing |
| Version | 4.45.4 |
| Effort | high |
| 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
How to invoke
Section titled “How to invoke”/t1k:unity:testing:workflowUnity Testing Workflow
Section titled “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; seecode-conventions.md§ “Modular Boundaries” for the rule andt1k-unity-base-project-structure§ Layer 3 for the Unity layout. (2) Where the logic belongs — Tier-2/Tier-3 game rules live off theMonoBehaviourpert1k-game-arch, so a test needs no scene and no Play mode. DOTS carve-out: anISystemis already the logic layer and is already headless-testable viaDOTSTestBase— never extract one into a plain class.
When to Use
Section titled “When to Use”- 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
Critical Assembly Configuration
Section titled “Critical Assembly Configuration”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.
Quick Discovery Checklist
Section titled “Quick Discovery Checklist”Tests don’t appear? Verify in order:
-
UnityEngine.TestRunnerin references -
UnityEditor.TestRunnerin references -
"includePlatforms": ["Editor"] -
"overrideReferences": true -
"precompiledReferences": ["nunit.framework.dll"] -
"defineConstraints": ["UNITY_INCLUDE_TESTS"] - Test class
public+[TestFixture] - Test methods
public+[Test] -
.metafiles exist for all test files - 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-cliSKILL.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.
The order, every time
Section titled “The order, every time”# 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.shUED=~/Unity/Hub/Editor/<version>/Editor/Unityunity_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 buildls 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
-quitvariant, why the GUI can SIGSEGV on 6000.5, why error counts rise as you fix), seereferences/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”ps -eo comm --no-headers | grep -E '^Unity Main' # correctps -eo comm --no-headers | grep -qx Unity # WRONG — can never matchpgrep -af "Unity.*<project>" # correct — but read the output, don't test itps -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.
Batch Mode Execution
Section titled “Batch Mode Execution”source .claude/scripts/unity-batch-gate.sh # every headless launch goes through the machine-wide gateunity_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# Analyze failuresgrep -B 5 'result="Failed"' TestResults.xmlgrep '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:
- Subject built with
new— noAddComponent, noGameObject, noScriptableObject.CreateInstance [Test], never[UnityTest]/yield return null, never Play mode- Time / randomness / input passed in (
Advance(float dt), injected seed, input struct) — neverTime.deltaTime,Random.value, orInput.*read inside the logic - 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.
Red Flags
Section titled “Red Flags”- Missing
includePlatforms: ["Editor"]— most common cause of tests not appearing - Missing
UnityEngine.TestRunnerorUnityEditor.TestRunnerreference - Test class or method not
public .metafiles missing (causes import issues)- Not clearing cache after config changes
Hard rules
Section titled “Hard rules”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.
Integration with Other Skills
Section titled “Integration with Other Skills”t1k-unity-dots-testing-unit-testing— DOTS ECS test patternst1k-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-flakyUpdate()gotcha (logic takingdtas a parameter is never focus-flaky and never needs reflection)t1k-unity-base-project-structure— where a module’sTests/EditMode/asmdef lives
Reference Files
Section titled “Reference Files”| File | Contents |
|---|---|
references/test-assembly-config.md | Full .asmdef template, folder structure, meta files, test code patterns |
references/test-debugging-guide.md | Discovery checklist, cache clearing, compilation errors, systematic debug |
references/batch-mode-guide.md | CLI execution, CI integration, XML format, coverage limitation, the machine-wide batch gate |
references/ci-licence-free-lane.md | Running 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.md | Batchmode 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.md | Running 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.md | Mutation 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.md | What 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 |