t1k:unity:testing:code-coverage
| Field | Value |
|---|---|
| Module | testing |
| Version | 4.45.4 |
| Effort | high |
| Tools | — |
Keywords: code coverage, quality, testing
How to invoke
Section titled “How to invoke”/t1k:unity:testing:code-coverageUnity Code Coverage
Section titled “Unity Code Coverage”Package: com.unity.testtools.codecoverage v1.3.0. Measures which lines execute during tests; generates HTML/XML reports. For DOTS library coverage, GUI mode only — batch mode does NOT capture Packages/ assemblies.
Critical Limitation — UPM Packages + Batch Mode
Section titled “Critical Limitation — UPM Packages + Batch Mode”Batch mode reports 0% coverage for all Packages/com.the1studio.* assemblies. This is a Unity engine limitation — not a config issue. No flag (assemblyFilters, pathFilters, --burst-disable-compilation) fixes it.
See
references/batch-mode-limitation.mdfor all attempted workarounds.
How “Enable Code Coverage” Is Stored (Investigation 2026-03-14)
Section titled “How “Enable Code Coverage” Is Stored (Investigation 2026-03-14)”The toggle uses two separate mechanisms:
CoveragePreferences(persisted) —CoveragePreferences.instance.SetBool("EnableCodeCoverage", value)writes toProjectSettings/Packages/com.unity.testtools.codecoverage/Settings.jsonviaUnityEditor.SettingsManagement.SettingsAPICoverage.enabled(runtime) — Unity C# API flag, set alongside the preference. This is the actual runtime gate that controls instrumentation
Settings.json hard rule
Section titled “Settings.json hard rule”Settings.json starts EMPTY (m_DictionaryValues: []) even after enabling coverage via the GUI toggle. The file only populates when the user toggles the checkbox inside the Code Coverage window (Window > Analysis > Code Coverage). Enabling it elsewhere (e.g., batch mode -enableCodeCoverage flag) does NOT write to Settings.json.
On domain reload, the Code Coverage window reads Coverage.enabled (runtime API) to sync its state — it does NOT read from Settings.json for the initial enable state.
Headless Configuration (Text-Based)
Section titled “Headless Configuration (Text-Based)”Edit ProjectSettings/Packages/com.unity.testtools.codecoverage/Settings.json directly:
{ "m_Dictionary": { "m_DictionaryValues": [ { "type": "System.Boolean, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089", "key": "EnableCodeCoverage", "value": "{\"m_Value\":true}" }, { "type": "System.String, mscorlib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=b77a5c561934e089", "key": "IncludeAssemblies", "value": "{\"m_Value\":\"DOTSRPG.Core,DOTSRPG.Combat\"}" } ] }}Important: Writing this file persists the preference, but Coverage.enabled is only set at editor startup or when the Code Coverage window reads this file. After editing, run t1k unity refresh or restart Unity.
GUI Workflow (Required for Library Coverage)
Section titled “GUI Workflow (Required for Library Coverage)”- Window > Analysis > Code Coverage (ensure “Enable Code Coverage” checked)
- Window > General > Test Runner > EditMode tab
- Click “Run All”
- Report auto-opens:
CodeCoverage/Report/index.html
Batch Mode (Assets/ Code Only)
Section titled “Batch Mode (Assets/ Code Only)”Use for demo code in Assets/Demos/ — NOT for Packages/:
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")" ./TestResults.xml \ -projectPath "/path/to/project" -nographics -testPlatform EditMode \ -debugCodeOptimization --burst-disable-compilation \ -enableCodeCoverage \ -coverageResultsPath ./CodeCoverage/Results \ -coverageOptions "generateHtmlReport;assemblyFilters:+<assets>;pathFilters:-**/Tests/**"Required flags:
-debugCodeOptimization— Debug mode required; Release mode gives inaccurate data--burst-disable-compilation— Burst prevents coverage instrumentation-enableCodeCoverage— ActivatesCoverage.enabledat startup
Assembly Filters
Section titled “Assembly Filters”| Pattern | Captures |
|---|---|
+<assets> | All Assets/ assemblies (batch-safe) |
+<packages> | Package assemblies (batch mode = 0%, GUI = full) |
+my.package.name | Specific package by name |
-**/Tests/** | Exclude test files from coverage |
Hard rules
Section titled “Hard rules”- Burst blocks ALL runtime system coverage —
[BurstCompile]systems show 0% even in GUI mode because Burst-compiled code bypasses managed C# instrumentation. Must disable Burst (Jobs > Burst > Enable Compilation uncheck) before running tests for coverage. Batch mode uses--burst-disable-compilationbut that flag only works for Assets/ code - GUI mode + Burst enabled = misleading results — Tests PASS (362/362) but runtime systems show 0% coverage. Only non-Burst code shows coverage: struct constructors (
DamageEvent,StatusEffect), constants classes, pure utility structs called directly (SpatialHashGridat 92.8%) - ISystem IS coverable —
OnCreate/OnUpdateinstrumented when Burst is disabled - Components are data-only — No logic = no coverage needed
- IJobEntity coverage — Job body covered when Burst disabled and system is covered
[ExcludeFromCoverage]— Use sparingly; doesn’t reliably exclude lambdas- Settings.json empty — Normal. Only populates after explicit GUI toggle in Code Coverage window
GUI Workflow for Accurate DOTS Coverage
Section titled “GUI Workflow for Accurate DOTS Coverage”- Jobs > Burst > Uncheck Enable Compilation
- Window > Analysis > Code Coverage > Enable Code Coverage
- Window > General > Test Runner > EditMode > Run All
- Review report at
CodeCoverage/Report/index.html - Re-enable Burst after coverage run (performance impact otherwise)
CI/CD Recommendation
Section titled “CI/CD Recommendation”Batch mode is useless for package coverage. Instead:
- Run tests in batch (no coverage flags), use test count as coverage proxy
- 362 tests passing = strong coverage signal for
com.the1studio.dots-core - For true coverage metrics, run GUI mode locally with Burst disabled before merging
Report Location
Section titled “Report Location”CodeCoverage/Report/index.html — auto-generated after test run with coverage enabled.
Executed by
Section titled “Executed by”The measure-and-report half delegates to cheap-tier agents; only the interpretation stays on a
reasoning tier (routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”):
| Step | Agent |
|---|---|
| Read the coverage report files and quote the per-assembly line/branch coverage numbers | t1k-fact-fetcher |
| Aggregate the per-assembly coverage figures into the report table | t1k-metrics-reporter |
| Label whether each assembly’s coverage meets the stated threshold | t1k-list-classifier |
| Run the GUI coverage session (disable Burst, enable Code Coverage, run tests) | reasoning tier — GUI orchestration and the Coverage.enabled / Settings.json dance are not enumeration |
| Judge what a 0% package figure means (batch-mode limitation vs. real gap) | reasoning tier — diagnosing WHY a number is wrong is t1k-debugger |
The measurement is fully specified: report files exist at CodeCoverage/Report/index.html, the
numbers to read are named, and the thresholds are stated. The moment the question turns from
what is the coverage figure? to why is Packages/ 0% and does the batch-mode limitation explain
it, it has changed tier — a wrong-looking number is a diagnosis, not a measurement, and this
skill’s own gotchas exist precisely because that diagnosis is non-trivial
Related
Section titled “Related”t1k-unity-dots-testing-unit-testing— Test fixture patterns (DOTSTestBase, ISystem isolation)t1k-unity-dots-core-testeragent — Test execution viat1k unity test
Reference Files
Section titled “Reference Files”| File | Content |
|---|---|
references/batch-mode-limitation.md | All attempted workarounds + evidence |