Skip to content
T1KTheOneKit

t1k:unity:testing:workflow

FieldValue
Moduletesting
Version3.1.7
Efforthigh
Tools—

Keywords: test runner, testing, unity, workflow

How to invoke

Section titled “How to invoke”
/t1k:unity:testing:workflow

Unity Testing Workflow

Section titled “Unity Testing Workflow”

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

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
  • 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:

  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.

Batch Mode Execution

Section titled “Batch Mode Execution”
Terminal window
unity-editor \
    -runTests -batchmode \
    -projectPath /path/to/project \
    -testResults /path/to/results.xml \
    -testPlatform EditMode \
    -logFile /path/to/test.log
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.

Red Flags

Section titled “Red Flags”
  • 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

Gotchas

Section titled “Gotchas”
  • Missing asmdef test references: Test assembly must reference UnityEngine.TestRunner AND UnityEditor.TestRunner — missing either causes tests to silently not appear in Test Runner
  • UNITY_INCLUDE_TESTS define required: Without "defineConstraints": ["UNITY_INCLUDE_TESTS"] in the test asmdef, test code compiles but tests are excluded from discovery
  • Batch mode skips GUI-dependent tests: Tests using EditorWindow, modal dialogs, or visual assertions fail or are skipped in -batchmode. Design tests to be headless-compatible for CI
  • Companion test rule for new ECS subsystem clusters — when adding a new subsystem cluster (e.g., DraftSystem + BoardPlacementSystem + RoundManagementSystem), EVERY ISystem in the cluster requires a test. Testing only the orchestrator (RoundManagementSystem) while skipping DraftSystem and BoardPlacementSystem creates false confidence — the untested systems are often where real bugs live. Audit (260520-R6) found 22 untested ISystems across 11 packages following this pattern. File a companion test task alongside every new system implementation task. Source: review-260520-round6-test-coverage.md §T4
  • EditMode tests that invoke a MonoBehaviour’s real Update() are focus-flaky via Time.deltaTime: In EditMode, Time.deltaTime / Time.unscaledDeltaTime is ~0 when the editor is unfocused but a real (often >1s) frame delta when focused — so a test that drives a component by calling its private Update() (which internally does Advance(Time.deltaTime)) passes unfocused and fails focused (or vice versa), with no code change. Symptom: the same test passes in most runs and fails only occasionally, correlated with editor_is_focused flipping; the assertion is real (e.g. alpha expected 1, got 0) but non-deterministic. Author tests with controlled dt: expose a private Advance(float dt) (or split detection from advancement) and have the test call it via reflection with explicit dt values — never rely on the real Update() to advance time. Component-side robustness (also gameplay-correct): on the frame a state transition is detected, render t=0 with Advance(0f) and return — do NOT consume the pre-transition delta (a loading hitch / pause / the gap between manual EditMode Update() calls must not fast-forward a freshly-started animation past its cycle). Real incident: BackpackBattlefieldPhaseBanner 2026-05-29.

Integration with Other Skills

Section titled “Integration with Other Skills”
  • dots-unit-testing — DOTS ECS test patterns
  • unity-code-coverage — Code coverage reports (Editor GUI only, not batch mode)

Reference Files

Section titled “Reference Files”
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