.NET packages

Install

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

# Implement an engine adapter
dotnet add package Gua.Runtime

# Launch an engine process from an external test
dotnet add package Gua.Testing.Godot
dotnet add package Gua.Testing.Unity

# Optional capabilities
dotnet add package Gua.Testing.Visual
dotnet add package Gua.Testing.Recording

Without --version, the .NET CLI resolves the latest stable package available on NuGet. For reproducible builds, commit the resulting project or central package file and keep all Gua packages on the same version line. Visual and Recording are independent opt-ins, so ordinary semantic tests do not inherit PNG codecs or recording behavior.

NuGet: Core · Testing · Testing.Godot · Testing.Unity · Runtime · Testing.Visual · Testing.Recording

Choose a package

Target frameworks

Gua.Core

The lowest .NET layer over the native C ABI. It defines the UI-tree, request, and event contracts.

Gua.Runtime

Gua.Runtime is for managed engine-adapter authors, not ordinary test authors. It exposes the shared gua_runtime C ABI through typed APIs so adapters do not duplicate P/Invoke declarations, request queues, screenshot timeout handling, version publication, or Inspector WebSocket hosting. Choose it when integrating an engine other than Godot or Unity, or when adapting a custom UI framework. See the Gua.Runtime implementation guide.

Gua.Testing.Unity

UnityPlayerBuilder and UnitySceneTestHost connect external tests to Unity 6 Windows x64 Mono Players or Editor Play Mode. Use it to delegate Unity executable discovery, free-port allocation, bridge connection, and startup/teardown log capture to the host. See the Unity API reference for the public API and support boundaries.

Gua.Testing

Adds the higher-level API consumed by tests.

Gua.Testing.Godot

Starts a Godot process and connects to its in-game WebSocket bridge.

Gua.Testing.Visual

An opt-in layer for comparing explicitly captured PNGs with reviewed baselines. A semantic assertion may prove that a button is visible while missing that it is clipped, overlapping another control, using the wrong asset, or covered by an unexpected overlay. Visual testing closes that gap. It supports pixel thresholds, allowed difference ratios, masks, explicit OS/renderer variants, and dimension mismatch detection. See the visual testing guide for setup and CI policy.

var result = await GuaVisualAssertions.ExpectScreenshotAsync(
    host.Context, "title-screen", new()
    {
        BaselineDirectory = "baselines",
        ArtifactDirectory = "artifacts/gua",
        BaselineVariant = "windows-unity-mono",
        PixelThreshold = 0.02f,
        MaxDifferentPixelRatio = 0.001,
    });

comparison.json records the comparison name, variant, actual dimensions, different-pixel metrics, thresholds, masks, failure reason, and diagnostic absolute baselinePath. The package does not generate HTML; the gua-tester visual-report action owns rendering and publication. Normal CI must not update its own baselines. Keep resolution, DPI, fonts, locale, theme, engine, and renderer deterministic, and mask only genuinely nondeterministic regions.

Gua.Testing.Recording

Stores multi-step journeys such as login, settings changes, or purchase confirmation as semantic actions for regression testing and bug reproduction. It records IDs and roles instead of coordinates, and waits for request-ID-correlated host completion on replay, making it more reliable than a fixed-delay macro. See the recording guide for complete workflows.

var recorder = new GuaRecorder(host.Context);
await recorder.ClickAsync(new(Id: "open-login"));
await recorder.SetValueAsync(new(Id: "password"), password,
    sensitive: true, secretKey: "login-password");
GuaRecordingFile.Save("recordings/login.json", recorder.Recording);

var recording = GuaRecordingFile.Load("recordings/login.json");
await GuaReplayer.ReplayAsync(host.Context, recording, new()
{
    SecretResolver = key => key == "login-password" ? password : null,
});

GuaRecorder, GuaReplayer, and GuaRecordingFile support semantic wait conditions in place of fragile delays. Sensitive set_value steps store only a secretKey, never plaintext. Coordinate fallback is disabled by default.