Testing UI

1. Add test packages

Gua.Testing.Unity is published on NuGet. These commands resolve the latest compatible stable packages; commit the versions written to the project and keep the three Gua packages on the same version line.

dotnet add package Gua.Core
dotnet add package Gua.Testing
dotnet add package Gua.Testing.Unity

Align the game integration and related Gua package versions. See version management for recording and pinning the result.

2. Start a Player or Editor

using Gua.Core;
using Gua.Testing;
using Gua.Testing.Unity;

var player = UnityPlayerBuilder.Build(@"game/Assets/Scenes/Title.unity");
using var host = UnitySceneTestHost.LoadRenderedPlayer(
    player, UnitySceneTestHostOptions.StrictIsolation);
GuaAssertions.GetByRole(
    host.Context, "button", "Start Game"
).ToBeVisible();

await GuaAssertions.GetById(
    host.Context, "start"
).ClickAsync();

await GuaAssertions.WaitForTextAsync(
    host.Context, "loading", "Loading..."
);

var screenshot = host.CaptureScreenshot();

3. Use the same semantic API as Godot

host.Context is the engine-neutral IGuaContext. Tests use the same locators and waits instead of branching on Unity UI technology.

var name = GuaAssertions.Query(host.Context)
    .ByRole("textbox").Within("LoginForm");

await name.SetValueAsync("alice");
await name.FocusAsync();
await GuaAssertions.PressKeyAsync(host.Context, "Enter");

await GuaAssertions.GetById(host.Context, "RememberMe")
    .SetCheckedAsync(true);
await name.ByValue("alice").ResolveAsync();

Four rules for reliable Unity tests

Visual comparison and recording

Gua.Testing.Visual and Gua.Testing.Recording are engine-neutral packages, so both work with the host.Context supplied by Gua.Testing.Unity. Use LoadRenderedPlayer or Editor Play Mode when Visual needs a PNG. Recording operates on semantic actions and also works with a headless Player.

using Gua.Testing.Recording;
using Gua.Testing.Visual;

var comparison = await GuaVisualAssertions.ExpectScreenshotAsync(
    host.Context, "title-screen", new() {
        BaselineDirectory = "baselines",
        ArtifactDirectory = "artifacts/gua",
    });

var recorder = new GuaRecorder(host.Context);
await recorder.ClickAsync(new(Id: "start"));

Parallel isolation

UseAvailableBridgePort defaults to true. The host selects a loopback port and passes it as GUA_BRIDGE_PORT, avoiding a fixed collision on port 8765. It closes the listener before Unity binds, so a small selection-to-bind race remains under extreme concurrency.

var options = new UnitySceneTestHostOptions {
    UnityExecutablePath = @"C:/Program Files/Unity/Hub/Editor/6000.5.3f1/Editor/Unity.exe",
    ProjectPath = @"C:/src/game",
    UseAvailableBridgePort = true,
    TeardownResetPolicy = GuaResetPolicy.Strict,
    CaptureDiagnosticsBeforeTeardown = true,
};

Diagnostics

CreateDiagnosticsSession() adds the single -logFile Unity log, PID, bridge URL, and log path to shared artifacts. stdout and stderr are not redirected separately. Strict teardown reports leaked requests or events instead of deleting them silently.

using var diagnostics = host.CreateDiagnosticsSession(
    TestContext.CurrentContext.Test.FullName,
    outputDirectory: "artifacts/gua",
    captureScreenshot: true);

using var assertionScope = GuaAssertionScope.Use(
    new GuaAssertionOptions {
        DiagnosticsSession = diagnostics,
    });

GuaAssertions.GetByRole(
    host.Context, "button", "Start Game"
).ToBeVisible();

SceneTimeout currently serves mainly as the default screenshot timeout; it does not wait for scene transitions automatically.

Wait for actionable UI

Gua.Testing locators resolve a current strict single match when used. Actions wait for visible/enabled state and the advertised action, then correlated host completion. Multiple matches fail immediately. Resolution, enqueue, and completion share one timeout budget; rejected enqueue and host failure are not automatically retried.

using Gua.Testing;

var play = GuaAssertions.Query(host.Context).ByRole("button", "Play");
await play.ClickAsync(timeout: TimeSpan.FromSeconds(5));
await GuaAssertions.Query(host.Context).ById("game-screen").ResolveAsync();

ResolveAsync waits for the next node to exist; add the state assertion your test requires. Locator API and timeout rules.

Compare semantic state without pixels

Add Gua.Testing.Snapshots to compare UI IDs, hierarchy, text, values, and state against reviewed JSON baselines. It works with host.Context, including a headless host. Add Gua.Testing.Visual separately when rendered pixels matter. Installation, masks, and baseline update example.

dotnet add package Gua.Testing.Snapshots

Save test evidence with Gua.Testing Trace

Trace belongs to Gua.Testing; no extra Trace package is needed. Enable it for a test scope, complete it with the test's actual outcome, and create an offline HTML report at a new output path.

using Gua.Testing;

await using var trace = new GuaTraceSession(new() {
    OutputDirectory = "artifacts/traces",
    SavePolicy = GuaTraceSavePolicy.Always,
});
using var scope = GuaAssertionScope.Use(new() { Trace = trace });
try {
    await GuaAssertions.Query(host.Context).ById("play").ClickAsync();
    await trace.CompleteAsync(GuaTraceOutcome.Passed);
} catch {
    await trace.CompleteAsync(GuaTraceOutcome.Failed);
    throw;
}
var report = GuaTraceReport.WriteHtml(trace.ArtifactPath, "artifacts/report.html");
// Check report.Succeeded and trace.Status separately from the test result.

Trace records evidence; it does not replay the flow or change its result. Capture UI/World or Observe values explicitly when required, and handle sensitive data before recording. Trace capture APIs · Open a saved Trace in Inspector.

Support when selecting a host

Unity 6000.5.3f1 desktop Mono Players are implemented and verified on Windows, Linux, Intel macOS, and Apple Silicon macOS. Editor Play Mode is verified on Windows, Linux, and Apple M4; native Intel macOS Editor is implemented but unverified. See Unity APIs and limits.