GoDotTest

For games, you should integrate GoDotTest into your main entry point so it can detect command-line arguments and decide whether to run tests or start the game.

1. Exclude tests from release builds: Add this to your .csproj to prevent test files from being included in exported release builds:

<PropertyGroup>
  <DefaultItemExcludes Condition="$(Configuration)' == 'ExportRelease'">
    $(DefaultItemExcludes);test/**/*
  </DefaultItemExcludes>
</PropertyGroup>

2. Implement the Main entry point logic: In your main scene (e.g., Main.tscn), use TestEnvironment.From(OS.GetCmdlineArgs()) to check if tests should run. If they should, call GoTest.RunTests. Otherwise, switch to your actual game scene (e.g., Game.tscn).

namespace YourGame;

using Godot;

#if DEBUG
using System.Reflection;
using GoDotTest;
#endif

public partial class Main : Node2D
{
#if DEBUG
  public TestEnvironment Environment = default!;
#endif

  public override void _Ready()
  {
#if DEBUG
    // If this is a debug build, use GoDotTest to examine the
    // command line arguments and determine if we should run tests.
    Environment = TestEnvironment.From(OS.GetCmdlineArgs());
    if (Environment.ShouldRunTests)
    {
      CallDeferred("RunTests");
      return;
    }
#endif
    // If we don't need to run tests, our game will start and immediately switch to the game scene.
    GetTree().ChangeSceneToFile("res://src/Game.tscn");
  }

#if DEBUG
  private void RunTests()
    => _ = GoTest.RunTests(Assembly.GetExecutingAssembly(), this, Environment);
#endif
}

If your project is configured to switch to the test scene when the --run-tests flag is passed, you can use the coverlet tool to run Godot and collect code coverage.

Note that the --run-tests, --coverage, and --quit-on-finish flags are specific to GoDotTest. When the --coverage flag is supplied, GoDotTest will force-exit the process to ensure the exit code is set correctly for coverage tools, as Godot's SceneTree.Quit(int exitCode) does not set the process exit code. This may cause minor error messages during exit, which can be safely ignored.

coverlet \
  "./.godot/mono/temp/bin/Debug" --verbosity detailed \
  --target $GODOT \
  --targetargs "--run-tests --coverage --quit-on-finish" \
  --format "opencover" \
  --output "./coverage/coverage.xml" \
  --exclude-by-file "**/test/**/*.cs" \
  --exclude-by-file "**/*Microsoft.NET.Test.Sdk.Program.cs" \
  --exclude-by-file "**/Godot.SourceGenerators/**/*.cs" \
  --exclude-assemblies-without-sources "missingall"

To debug tests in VS Code, you must first set the GODOT environment variable to the path of your Godot executable (e.g., export GODOT="/Applications/Godot.app/Contents/MacOS/Godot" in your shell profile).

Then, place the following tasks.json and launch.json files in a .vscode folder at your project root.

// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "build",
      "command": "dotnet",
      "type": "process",
      "args": [
        "build",
        "--no-restore"
      ],
      "problemMatcher": "$msCompile",
      "presentation": {
        "echo": true,
        "reveal": "silent",
        "focus": false,
        "panel": "shared",
        "showReuseMessage": true,
        "clear": false
      }
    }
  ]
}

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Play",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build",
      "program": "${env:GODOT}",
      "args": [],
      "cwd": "${workspaceFolder}",
      "stopAtEntry": false,
    },
    {
      "name": "Debug Tests",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build",
      "program": "${env:GODOT}",
      "args": [
        "--run-tests",
        "--quit-on-finish"
      ],
      "cwd": "${workspaceFolder}",
      "stopAtEntry": false,
    },
    {
      "name": "Debug Current Test",
      "type": "coreclr",
      "request": "launch",
      "preLaunchTask": "build",
      "program": "${env:GODOT}",
      "args": [
        "--run-tests=${fileBasenameNoExtension}",
        "--quit-on-finish"
      ],
      "cwd": "${workspaceFolder}",
      "stopAtEntry": false,
    }
  ]
}

To write a test suite, create a class that extends TestClass. The constructor must accept a Node (the test scene) and pass it to the base class. You can use lifecycle attributes to manage the state of your tests.

Lifecycle Attributes:

• [SetupAll]: Runs once before the first test in the suite.
• [CleanupAll]: Runs once after all tests in the suite have finished.
• [Setup]: Runs before each individual test.
• [Cleanup]: Runs after each individual test.
• [Test]: Marks a method as a test case.
• [Failure]: Runs whenever any test in the same suite fails. Useful for taking screenshots or error management.

using Chickensoft.GoDotTest;
using Chickensoft.Log;
using Godot;

public class ExampleTest : TestClass
{
  private readonly ILog _log = new Log(nameof(ExampleTest), new TraceWriter());

  public ExampleTest(Node testScene) : base(testScene) { }

  [SetupAll]
  public void SetupAll() => _log.Print("Setup everything");

  [Setup]
  public void Setup() => _log.Print("Setup");

  [Test]
  public void Test() => _log.Print("Test");

  [Cleanup]
  public void Cleanup() => _log.Print("Cleanup");

  [CleanupAll]
  public void CleanupAll() => _log.Print("Cleanup everything");

  [Failure]
  public void Failure() =>
    _log.Print("Runs whenever any of the tests in this suite fail.");
}