Visualテスト実践 | Gua 日本語リファレンス

どんな不具合に使うか

Visualが有効	Semantic assertionを優先
Controlのclipping・重なり・位置ずれ	buttonが存在する、visibleである
誤ったtexture、font、theme、overlay	textやvalueが期待値である
解像度変更で崩れたlayout	操作後に画面・状態が遷移した
描画は成功したが見た目が異なる	高速で原因が明確な機能検証

Stable UI frame必要なら3 frame待機→Actual PNGdiagnosticsから取得→Reviewed baselinename + variant→Pixel comparisonthreshold・mask→PASS / artifacts差分をreview

図1: baselineはテスト名とvariantで選ばれ、許容条件を超えた場合だけ比較artifactを生成します。

導入

最新安定版をvisual test projectへ追加powershell

dotnet add package Gua.Testing.Visual

1. baselineを明示的に作る

baselineが無い通常実行は失敗します。初回または意図したUI変更時だけ、developerが明示的に更新します。

PowerShellでbaseline更新を許可powershell

$env:GUA_UPDATE_BASELINES = "1"
dotnet test tests/Game.Visual.Tests/Game.Visual.Tests.csproj
Remove-Item Env:GUA_UPDATE_BASELINES

生成されたPNGを目視reviewし、正しい場合だけtest repositoryへcommitします。通常のpull request jobにこの環境変数を設定してはいけません。

2. baselineをversion管理する

次の比較例はNUnitのtest output directoryからbaselineを読みます。test project直下のbaselinesへcommitしたPNGがclean checkoutやCIでもoutputへコピーされるよう、project fileへ次のruleを追加します。

Game.Visual.Tests.csprojxml

<ItemGroup>
  <None Update="baselines/**/*.png"
        CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>

baselineを作成・更新した場合は、outputに生成されたPNGを目視reviewし、承認したファイルをproject直下のbaselinesへ戻してからcommitしてください。

3. 通常実行で比較する

title画面を比較csharp

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

// 遷移とanimationが決定的になった後だけgame側が公開するnode
await GuaAssertions.WaitForVisibleAsync(host.Context, "visual-ready");

var baselineVariant = Environment.GetEnvironmentVariable("GUA_VISUAL_VARIANT")
    ?? "windows-unity-mono-1920x1080";

var result = await GuaVisualAssertions.ExpectScreenshotAsync(
    host.Context,
    "title-screen",
    new ScreenshotOptions
    {
        BaselineDirectory = Path.Combine(TestContext.CurrentContext.TestDirectory, "baselines"),
        ArtifactDirectory = Path.Combine(TestContext.CurrentContext.WorkDirectory, "artifacts", "gua"),
        BaselineVariant = baselineVariant,
        PixelThreshold = 0.02f,
        MaxDifferentPixelRatio = 0.001,
        WaitForStableSnapshot = true,
        StableFrames = 3,
    });

WaitForStableSnapshotが確認するのはSemantic UI snapshotが変化しなくなったことだけです。sprite、shader、caret、画面遷移等のpixel animation停止は検出しません。上の例のようにapplication固有のready条件を先に待ち、animation状態を決定的にしてください。PixelThresholdは各channelの微差、MaxDifferentPixelRatioは差があるpixelの割合を許容します。最初から大きな値を設定せず、renderer由来の安定した差だけを根拠に調整します。

失敗時に残るもの

理由	ファイル
`pixel_difference`	`expected.png`、`actual.png`、`diff.png`、`comparison.json`
`baseline_missing`	`actual.png`、`comparison.json`
`dimension_mismatch`	`expected.png`、`actual.png`、`comparison.json`

ArtifactDirectoryを指定すれば、通常のGua diagnosticsと同じ失敗directoryへVisual artifactをまとめられます。dimension mismatchは暗黙にresizeせず失敗します。Gua.Testing.Visualはデータだけを出力してHTMLを生成しません。静的Viewerの構築にはvisual-report Actionを使います。

variantとmask

設定	使い方	避けること
`BaselineVariant`	OS、engine、renderer、解像度など正当な描画差を名前へ含める	失敗するたび新variantを増やす
`Masks`	時計、乱数avatarなど本当に非決定的な矩形だけ除外	重要UI全体をmaskして回帰を隠す
`WaitForStableSnapshot`	application-ready条件の後、Semantic stateが変化しないことを確認	pixel animationを停止・検出できると仮定する

非決定領域を限定してmaskcsharp

Masks = new[]
{
    new GuaMaskRectangle(X: 1710, Y: 24, Width: 180, Height: 48), // clock only
};

CI運用

PRで閲覧可能なレポートを保存yaml

- name: Run visual tests
  id: visual-tests
  shell: pwsh
  env:
    GUA_VISUAL_VARIANT: windows-unity-mono-1920x1080
  run: dotnet test tests/Game.Visual.Tests/Game.Visual.Tests.csproj --configuration Release

- name: Upload visual report
  if: failure()
  uses: link1345/gua-tester/visual-report@v2.2
  with:
    artifact-path: artifacts/gua
    test-outcome: failure
    upload-target: workflow

CIでは解像度、DPI scaling、font、locale、theme、engine version、renderer、GPU/driver policyを固定します。baseline更新は通常jobから分離し、差分reviewを必須にします。