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

ゲーム側の導入物とテストプロジェクトのGuaパッケージは同じバージョンに合わせます。Visual、Snapshots、Recordingは必要に応じて追加します。

導入したバージョンを確認する

版指定なしのコマンドは、設定済みのNuGetソースから互換性のある最新安定版を実行時に選びます。具体的な版は.csprojへ、中央管理ではDirectory.Packages.propsへ記録されます。後日のビルドだけで常に最新版へ更新されるわけではありません。記録したファイルをcommitし、ゲーム側と関連するGuaパッケージの版を揃えます。既存のゲームやCIに合わせる場合は--versionで実際の版を指定してください。公式CLI仕様

NuGet: Core · Testing · Testing.Godot · Testing.Unity · Runtime · Testing.Visual · Testing.Snapshots · 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、Linux x64、Intel macOS、Apple Silicon macOSのdesktop Mono Player、またはEditor Play Modeを外部テストへ接続します。native Intel macOSのEditor対応は実装済み・未検証です。Unity実行ファイルの探索、空きportの割り当て、bridge接続、起動・終了時のlog収集にhostを使います。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.Snapshots

UIと任意のWorldのJSONを正規化し、baselineと比較する独立したオプトイン層です。CompareSnapshotは型付き結果を返し、ExpectSnapshotは不一致時にその結果を保持する例外を送出します。ID、階層、意味的なproperty、配列の公開順序は比較対象です。geometryとruntime metadataは既定で除外し、PNGの比較にはVisualを使います。

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);

baselineがない場合も失敗し、自動作成しません。更新はUpdateBaselines = trueまたは正確にGUA_UPDATE_SEMANTIC_BASELINES=1で明示します。通常CIでは無効にし、差分をreviewしてcommitしてください。Visual用のGUA_UPDATE_BASELINESはSemantic baselineを更新しません。

mask/ignoreは保存前に設定し、すべての機密値の表現を対象にしてください。自動的な秘密検出はありません。maskはScreenshotやTraceの別観測を伏せません。比較ごとのartifactにはactual.json、任意のexpected.json、diff.json、comparison.jsonが含まれます。任意のWorldTreeProviderはUIと順次取得されるため、同一frameが必要なら呼び出し側で安定したtreeを用意します。1.1.0のAPI・rule契約を参照してください。

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は既定で無効です。

ゲーム側の追加観測はRuntimeガイド、Traceと操作待機はテストガイドを参照してください。TypeScriptの値処理はValueツール、AI接続はnpmパッケージで説明します。

用途からAPIを選ぶ