EasyTestBridge

An in-game testing bridge for Godot 4 C# projects.

EasyTestBridge runs inside your game as an autoload singleton. It provides a WebSocket server for remote inspection, input simulation, state capture, and a built-in test runner with [GameTest] attribute.

Features

• WebSocket Server (port 9876) for remote game inspection
• Node Registration and state inspection via reflection
• Input Simulation — keyboard, mouse, actions, text
• State Capture — FPS/memory metrics, log collection, viewport screenshots, scene tree
• Built-in Test Runner with [GameTest] attribute
• TestAssert assertion library (isTrue, areEqual, isNull, etc.)
• TestContext async utilities (waitFrames, waitSeconds, waitUntil)
• Tag-based test filtering

Requirements

• Godot 4.4+ (Mono/C#)
• .NET 8 SDK

Installation

From Godot Asset Library

1. Open Godot Editor → AssetLib tab
2. Search "EasyTestBridge"
3. Download and install
4. Enable the plugin: Project → Project Settings → Plugins → EasyTestBridge ✓

Manual

1. Copy addons/EasyTestBridge/ into your project's addons/ folder
2. Enable the plugin: Project → Project Settings → Plugins → EasyTestBridge ✓

Setup Autoload

Add EasyTestBridge as an autoload singleton:

Project → Project Settings → Autoload → Add:

• Path: res://addons/EasyTestBridge/EasyTestBridge.cs
• Name: EasyTestBridge

Quick Start

1. Register Nodes

In your game node's _Ready():

var bridge = GetNode<EasyTestBridge.EasyTestBridge>("/root/EasyTestBridge");
bridge.Registry.Register("player", this);

2. Register Actions

bridge.Registry.RegisterAction("reset_player", _ =>
{
    Health = 100;
    return TestBridgeServer.Respond(true, "player reset");
});

3. Write Tests

using EasyTestBridge.Testing;

public class PlayerTests
{
    [GameTest(Tag = "player")]
    public void Player_InitialHealth()
    {
        TestAssert.areEqual(100, 100);
    }

    [GameTest(Tag = "player", TimeoutMs = 5000)]
    public async Task Player_Movement(TestContext ctx)
    {
        await ctx.waitFrames(10);
        TestAssert.isTrue(true);
    }
}

4. Register Test Suites

Create an autoload to register your test suites:

public partial class TestRegistrar : Node
{
    public override void _Ready()
    {
        var bridge = GetNode<EasyTestBridge.EasyTestBridge>("/root/EasyTestBridge");
        bridge.TestRunner.registerSuite(new PlayerTests());
    }
}

Tests run automatically on startup when RunTestsOnStart = true (default).

Configuration

WebSocket Commands

Connect to ws://localhost:9876 and send JSON:

See docs/websocket-protocol.md for full protocol reference.

TestAssert API

TestContext API

Notes

• EasyTestBridge is automatically disabled in release builds (OS.IsDebugBuild())
• The demo/ folder is included for reference — you can safely delete it from your project

License

MIT