.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.Snapshots
dotnet add package Gua.Testing.Recording

Keep the game integration and all Gua packages in one project on the same version. Visual, Snapshots, and Recording are independent opt-ins.

Check the installed version

Without a version argument, the command selects the latest compatible stable version from the configured NuGet feeds when it runs. A concrete version is recorded in .csproj, or Directory.Packages.props with central management. Later builds do not continually update it to the latest release. Commit those files and align the game integration and related Gua packages. For an existing game or CI, specify its actual version with --version. Official CLI specification

NuGet: Core · Testing · Testing.Godot · Testing.Unity · Runtime · Testing.Visual · Testing.Snapshots · 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 desktop Mono Players on Windows x64, Linux x64, Intel macOS, and Apple Silicon macOS, or to Editor Play Mode. Native Intel macOS Editor support is implemented but unverified. Use the host for Unity executable discovery, free-port allocation, bridge connection, and startup/teardown log capture. See the Unity API reference and support limits.

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.Snapshots

An independent opt-in layer that normalizes UI and optional World JSON before comparison with a baseline. CompareSnapshot returns a typed result; ExpectSnapshot throws an assertion exception carrying that result on failure. IDs, hierarchy, semantic properties, and array publication order remain significant. Geometry and runtime metadata are excluded by default; use Visual for PNG comparison.

using Gua.Testing.Snapshots;

var options = new SemanticSnapshotOptions
{
    BaselineDirectory = "baselines/semantic",
    ArtifactDirectory = "artifacts/semantic",
    BaselineVariant = "english",
    Rules = new[]
    {
        new SemanticSnapshotRule("/ui/nodes/*/text",
            SemanticSnapshotRuleAction.Mask, "account/name"),
    },
};
GuaSemanticSnapshots.ExpectSnapshot(host.Context, "settings", options);

Missing baselines fail without creating one. Update explicitly with UpdateBaselines = true or exactly GUA_UPDATE_SEMANTIC_BASELINES=1. Keep updates disabled in regular CI and review baseline diffs before committing them. Visual's GUA_UPDATE_BASELINES does not approve semantic baselines.

Configure mask/ignore rules before capture and cover every representation of sensitive data; there is no automatic secret detection. These rules do not redact screenshots or separate Trace observations. Each comparison retains actual.json, optional expected.json, diff.json, and comparison.json. An optional WorldTreeProvider is read sequentially with UI; callers must supply stable trees when a coordinated frame matters. See the 1.1.0 API and rule contract.

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.

See the Runtime guide for observations and the testing guide for Trace and action waits. For TypeScript values, see Value tools; for AI connections, see npm packages.

Choose the API for the task