Unity Headless Testing (VS Code)

Intro

How to run Unity tests and debug C# code entirely in VS Code without opening Unity’s GUI.

Based on this repo but adapted for Linux (Ubuntu).

• Node script → automates Unity test runs and result parsing.
• Unity → executes tests headless, generates XML results.
• VSCode → attaches the debugger to Unity so breakpoints in test C# code work.
• Python parser → converts raw Unity XML results into readable output.
• Benefit: saves CPU and time because Unity Editor doesn’t need to open.

---

Setup

Setup Overview

1. Find Unity paths → locate your Unity executable and test folders.
2. VSCode launch config → lets Node scripts launch Unity and attach debugger automatically.
3. Debug wait helper → pauses Unity until VSCode attaches.
4. Node script → runs Unity in batch mode and triggers Python parser.
5. Python parser → reads Unity XML and prints human-readable Pass/Fail results.
6. Running tests → how to actually debug and hit breakpoints.

Sample Project Structure

project-root/
│
├── .vscode/
│   └── launch.json
│
├── scripts/
│   ├── run-unity-tests.js
│   └── parseUnityTestResults.py
│
├── Assets/                         
│   │
│   ├── Scripts/
│   │       │
│   │       └── PlayModeTests/
│   │           └── DodgeballTests.cs
│   │
│   └── ...
│
│
├── TestResults/
│   └── results.xml

---

1. Find Unity Paths

Purpose: Ensure Unity executable and test scripts are correctly located. Needed so Node script can launch Unity in batch mode and access test assemblies.

• Find Unity executable path

# Unity executable path (replace with your version)
~/Unity/Editors/6000.0.65f1/Editor/Unity

If you can’t find it, search:

find ~ -name Unity -type f 2>/dev/null

Test that it works:

~/Unity/Editors/6000.0.65f1/Editor/Unity --version

Expected output:

6000.0.65f1

Optional: add Unity to PATH so Node script can call it directly:

echo 'export PATH=$PATH:/home/<your-username>/Unity/Editors/6000.0.65f1/Editor' >> ~/.bashrc
source ~/.bashrc

Verify:

Unity --version

Locate test folders:

ls Assets/Scripts/GameAIStudentWork/EditorModeTests
ls Assets/Scripts/GameAIStudentWork/PlayModeTests

Find test class in a file:

grep -r "class" Assets/Scripts/GameAIStudentWork/PlayModeTests/DodgeballTests.cs

public class DodgeballTests

—

2. VSCode Launch Config

Purpose: Configure VSCode to debug Node scripts and attach automatically to Unity. This allows hitting breakpoints in C# test files while Unity runs in batch mode.

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Test PlayMode",
      "type": "pwa-node",
      "request": "launch",
      "runtimeExecutable": "node",
      "program": "${workspaceFolder}/scripts/run-unity-tests.js",
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal",
      "env": {
        "TEST_MODE": "PlayMode",
        "TEST_FOLDER": "PlayModeTests",
        "TESTS": "Tests.DodgeballTests"
      },
      "serverReadyAction": {
        "pattern": "READY_TO_ATTACH",
        "action": "startDebugging",
        "name": "Attach to Unity"
      }
    },
    {
      "name": "Attach to Unity",
      "type": "vstuc",
      "request": "attach"
    }
  ]
}

---

3. Add Debug Helpers to Test File

• Purpose: Makes Unity pause until the debugger is attached, which ensures breakpoints in test scripts actually trigger.
  • Optional: Track time for running tests

• Add the following near the top of the test file

DebugHelpers

namespace DebugHelpers
{
    using System;
    using System.Diagnostics;
    using System.Threading;
    using NUnit.Framework;
 
    [SetUpFixture]
    public class DebugWaitAndTimer
    {
        public static Stopwatch StopwatchInstance { get; private set; }
 
        [OneTimeSetUp]
        public void OnSuiteStart()
        {
            StopwatchInstance = Stopwatch.StartNew();
            TestContext.Progress.WriteLine($"=== Test Suite Started: {DateTime.Now:yyyy-MM-dd HH:mm:ss} ===");
 
            if (Environment.GetEnvironmentVariable("WAIT_FOR_DEBUGGER") == "1")
            {
                TestContext.Progress.WriteLine("READY_TO_ATTACH: Waiting for VSCode debugger...");
                while (!Debugger.IsAttached)
                {
                    Thread.Sleep(100);
                }
            }
        }
 
        [OneTimeTearDown]
        public void OnSuiteEnd()
        {
            StopwatchInstance.Stop();
            TestContext.Progress.WriteLine($"=== Test Suite Finished (SetUpFixture) === Total Duration: {StopwatchInstance.Elapsed}");
        }
    }
 
    // Dummy test fixture to inject total duration into NUnit XML
    [TestFixture]
    public class ZZZ_TestSuiteFinalizer
    {
        [Test]
        public void LogTotalDuration()
        {
            var total = DebugWaitAndTimer.StopwatchInstance?.Elapsed ?? TimeSpan.Zero;
            TestContext.WriteLine($"=== Test Suite Finished === Total Duration: {total}");
            Assert.Pass();
        }
    }
}

---

4. Node Script: run-unity-tests.js

Purpose: Automates running Unity headless, passing environment variables, and invoking the Python parser to format test results.

scripts/run-unity-tests.js

const fs = require("node:fs");
const path = require("node:path");
const { spawnSync } = require("node:child_process");
 
const projectPath = process.cwd();
const projectName = path.basename(projectPath);
const testResultsDir = path.join(projectPath, "TestResults");
const testResultsPath = path.join(testResultsDir, `${projectName}.xml`);
const parserPath = path.join(projectPath, "scripts", "parseUnityTestResults.py");
 
const PYTHON = process.platform === "win32" ? "python" : "python3";
const UNITY = "Unity";
 
const TEST_MODE = process.env.TEST_MODE || "EditMode";
const TEST_FOLDER = process.env.TEST_FOLDER || "EditorModeTests";
const TESTS = process.env.TESTS || "Tests.ThrowTestEditorMode";
 
const args = [
  "-batchmode",
  "-logFile", "-",
  "-debugCodeOptimization",
  "-runTests",
  "-testPlatform", TEST_MODE,
  "-assemblyNames", TEST_FOLDER,
  "-testFilter", TESTS,
  "-projectPath", projectPath,
  "-testResults", testResultsPath,
];
 
fs.mkdirSync(testResultsDir, { recursive: true });
if (fs.existsSync(testResultsPath)) fs.unlinkSync(testResultsPath);
 
const testResults = spawnSync(UNITY, args, {
  stdio: "inherit",
  env: { ...process.env, WAIT_FOR_DEBUGGER: "1" },
});
if (testResults.error) console.error(testResults.error.message);
 
const parseResults = spawnSync(PYTHON, [parserPath, testResultsPath], { stdio: "inherit" });
if (parseResults.error) console.error(parseResults.error.message);
 
if (process.platform === "win32") {
  spawnSync("powershell", ["-NoProfile", "-Command", "Get-CimInstance Win32_Process | Where-Object { $_.CommandLine -match 'UnityDebugAdapter\\.dll' } | ForEach-Object { Stop-Process -Id $_.ProcessId -Force }"], { stdio: "ignore" });
} else {
  spawnSync("pkill", ["-f", "UnityDebugAdapter\\.dll"], { stdio: "ignore" });
}
 
process.exit(testResults.status && parseResults.status);

---

5. Python Parser

Purpose: Reads Unity test XML and prints a human-readable Pass/Fail summary.

scripts/parseUnityTestResults.py

#!/usr/bin/env python3
import sys
import xml.etree.ElementTree as ET
 
if len(sys.argv) != 2:
    print("Usage: parseUnityTestResults.py <xml_file>")
    sys.exit(1)
 
xml_file = sys.argv[1]
 
try:
    tree = ET.parse(xml_file)
    root = tree.getroot()
except Exception as e:
    print(f"Failed to parse XML: {e}")
    sys.exit(1)
 
for testcase in root.iter("test-case"):
    name = testcase.get("fullname")
    result = testcase.get("result")
    print(f"{result.upper()}: {name}")

• Make scripts executable:

bash

chmod +x scripts/run-unity-tests.js
chmod +x scripts/parseUnityTestResults.py

---

6. Running Tests & Hitting Breakpoints

Purpose: Step through Unity test code in VSCode.

1. Open a PlayMode test file (e.g., PlayModeTests.cs).
2. Go to Run and Debug (Ctrl+Shift+D).
3. Select launch config (Test PlayMode).
4. Click the green debug arrow.

✅ Node launches Unity headless. Unity pauses at WaitForDebuggerIfRequested(), VSCode attaches, and breakpoints work.

---

Test Results

Purpose: Quickly see which tests passed or failed without opening Unity GUI.

• Raw XML: TestResults/GameAIPrisonDodgeball_Spring2026.xml
• Human-readable output:

text

PASS: Tests.ThrowTestEditorMode.ThrowTest
FAIL: Tests.DodgeballTests.BallMissesWall

---