.NETパッケージ

インストール

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

# engine adapterを実装する場合
dotnet add package Gua.Runtime

# engine processを外部起動するテスト
dotnet add package Gua.Testing.Godot
dotnet add package Gua.Testing.Unity

# 必要な機能だけオプトイン
dotnet add package Gua.Testing.Visual
dotnet add package Gua.Testing.Recording

--versionを省略すると、.NET CLIがNuGetで公開されている最新の安定版を解決します。再現可能なbuildにするため、更新されたproject fileまたはcentral package fileをcommitし、Guaパッケージは同じバージョン系列へ揃えてください。VisualとRecordingは独立しており、通常のSemantic UIテストへPNG codecや記録機能を持ち込みません。

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

どのパッケージを選ぶか

Target Framework

Gua.Core

ネイティブC ABIを.NETから扱う最低層。UI Treeと要求・イベントの契約を提供する。

Gua.Runtime

Gua.Runtimeは、Guaを使うテスト作者ではなく、managed engine adapterの作者向けです。共有gua_runtime C ABIを型付きAPIとして公開し、各adapterがP/Invoke、request queue、screenshot timeout、version公開、Inspector WebSocket bridgeを重複実装するのを防ぎます。GodotやUnity以外のengineへGuaを組み込む場合、または独自UI framework adapterを作る場合に選びます。実装手順はGua.Runtime実装ガイドを参照してください。

Gua.Testing.Unity

UnityPlayerBuilderとUnitySceneTestHostで、Unity 6 Windows x64のMono PlayerまたはEditor Play Modeを外部テストへ接続します。Unity実行ファイルの探索、空きportの割り当て、bridge接続、起動・終了時のlog収集をhostへ任せたい場合に利用します。公開APIと対応範囲はUnity API・仕様を参照してください。

Gua.Testing

Coreの上へ、テストで読むための高水準APIを追加する。

Gua.Testing.Godot

Godotプロセスを起動し、ゲーム内WebSocketブリッジへ接続するホスト層。

Gua.Testing.Visual

明示的に取得したPNGをreview済みbaselineと比較するオプトイン層です。Semantic assertionで「ボタンが表示されている」と確認できても、そのボタンが切れている、重なっている、誤ったassetで描画されている、といった問題は残ります。この差を埋めるのがVisualテストです。pixel threshold、許容差分率、mask、OS/renderer別variant、dimension mismatchを扱います。詳しい導入・CI運用はVisualテスト実践を参照してください。

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には比較名、variant、実画像の寸法、差分metrics、閾値、mask、失敗理由、診断用の絶対baselinePathを記録します。パッケージ自身はHTMLを生成せず、表示と公開はgua-testerのvisual-report Actionが担当します。通常CIではbaselineを自動更新しません。更新は明示的なdeveloper操作に限定し、PNG差分をreviewしてからcommitします。

Gua.Testing.Recording

ログイン、設定変更、購入確認のような複数stepのユーザーフローをSemantic actionとして保存し、回帰テストやbug再現へ再利用する層です。座標ではなくID・role等のSemantic targetを記録し、再生時は各request IDに対応するhost完了eventまで待つため、単なる固定delayのmacroより安定します。詳しい記録・再生方法はRecording実践を参照してください。

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、GuaRecordingFileを提供し、固定delayよりSemantic wait conditionを優先できます。機密なset_valueは平文を保存せずsecretKeyだけを記録します。座標fallbackは既定で無効です。