LCOV - code coverage report
Current view: top level - vrt - golden.go Coverage Total Hit
Test: coverage.lcov Lines: 55.7 % 106 59
Test Date: 2026-11-19 00:25:22 Functions: - 0 0

            Line data    Source code
       1              : package vrt
       2              : 
       3              : import (
       4              :         "bytes"
       5              :         "fmt"
       6              :         "image"
       7              :         "image/png"
       8              :         "math"
       9              :         "os"
      10              :         "testing"
      11              : 
      12              :         "github.com/hajimehoshi/ebiten/v2"
      13              :         "github.com/sebdah/goldie/v2"
      14              :         "github.com/stretchr/testify/require"
      15              : )
      16              : 
      17              : // readScreen はebiten.Imageのピクセルデータを読み取りimage.NRGBAとして返す。解放はしない。
      18              : // 呼び出し側が所有する画像を渡されるときはこちらを使う
      19              : func readScreen(screen *ebiten.Image) *image.NRGBA {
      20            1 :         bounds := screen.Bounds()
      21            1 :         img := image.NewNRGBA(image.Rect(0, 0, bounds.Dx(), bounds.Dy()))
      22            1 :         screen.ReadPixels(img.Pix)
      23            1 :         return img
      24            1 : }
      25              : 
      26              : // captureScreen は readScreen したうえで ebiten.Image を解放する。
      27              : // このパッケージ内で作った使い捨ての描画先に使う
      28              : func captureScreen(screen *ebiten.Image) *image.NRGBA {
      29            1 :         img := readScreen(screen)
      30            1 :         screen.Deallocate()
      31            1 :         return img
      32            1 : }
      33              : 
      34              : // AssertScreenGolden は setupFn が返す描画関数で自前で ebiten.Image に描き、ゴールデン画像と比較する。
      35              : // レイアウト・描画は呼び出し側が制御する。messagelog・HUD など明示座標で Draw するコンポーネントに使う。
      36              : // world ごとに独立したフェイスで描くのでロックは要らない。
      37              : func AssertScreenGolden(t *testing.T, setupFn func() func(screen *ebiten.Image), width, height int) {
      38            0 :         t.Helper()
      39            0 : 
      40            0 :         drawFn := setupFn()
      41            0 :         screen := newScreen(width, height)
      42            0 :         drawFn(screen)
      43            0 :         img := captureScreen(screen)
      44            0 : 
      45            0 :         pngData := encodePNG(t, img)
      46            0 :         assertPNGGolden(t, t.Name(), pngData)
      47            0 : }
      48              : 
      49              : // Frame は vrt が作った描き先に描き終えた1枚の画。描き先を外から受け取らないので、golden に撮る画は
      50              : // 必ず newScreen の描き先に描かれる
      51              : type Frame struct {
      52              :         screen *ebiten.Image
      53              : }
      54              : 
      55              : // DrawFrame は width×height の描き先を作って draw で描き、その画を返す
      56              : func DrawFrame(width, height int, draw func(screen *ebiten.Image)) Frame {
      57            0 :         screen := newScreen(width, height)
      58            0 :         draw(screen)
      59            0 :         return Frame{screen: screen}
      60            0 : }
      61              : 
      62              : // AssertGolden は画を name のゴールデン画像 testdata/name.png と比較する。GOLDIE_UPDATE=1 で更新する
      63              : func (f Frame) AssertGolden(t *testing.T, name string) {
      64            0 :         t.Helper()
      65            0 :         assertPNGGolden(t, name, encodePNG(t, readScreen(f.screen)))
      66            0 : }
      67              : 
      68              : // newScreen は golden を撮る描き先を作る。共有アトラスに載せると配置が並行テストの生成順で変わり、
      69              : // 引き伸ばす画像のサンプル位置がずれるので unmanaged にする。機構は components.Texture を参照
      70              : func newScreen(width, height int) *ebiten.Image {
      71            0 :         return ebiten.NewImageWithOptions(image.Rect(0, 0, width, height), &ebiten.NewImageOptions{Unmanaged: true})
      72            0 : }
      73              : 
      74              : // encodePNG はimage.Imageをpngバイト列にエンコードする
      75              : func encodePNG(t *testing.T, img image.Image) []byte {
      76            1 :         t.Helper()
      77            1 :         var buf bytes.Buffer
      78            1 :         require.NoError(t, png.Encode(&buf, img))
      79            1 :         return buf.Bytes()
      80            1 : }
      81              : 
      82              : // noiseScale はトレランス算出の係数。
      83              : // ノイズはUI要素のエッジで発生し、エッジ量は画像面積の平方根に比例する。
      84              : // tolerance = noiseScale / √totalPixels で算出する。
      85              : //
      86              : // 960×720 の全画面ステートで約0.036%、約250画素、になる値にしている。VRT は
      87              : // Config.DisableScreenFilter でレトロフィルタを切って撮る。切ったあと、同一マシンでの
      88              : // ハードウェア GL とソフトウェア GL の差は振幅8bitで2以内に収まり、channelTolerance16 が
      89              : // 吸収する。取りこぼすのは mesa のバージョン差でグリフが1px ずれる位置ノイズで、これは
      90              : // 振幅255のエッジ反転として数えられる。アイコンを多く重ねた全画面ほどエッジが増え、
      91              : // CI のソフトウェア GL で標準の83画素を超えて落ちていた。250画素はそこへ余裕を持たせた値。
      92              : //
      93              : // 検出できる粒度: メニューのラベル2行を書き換えた実測が0.0825%、570画素、で検出する。
      94              : // 250画素はその半分より下なので実変化は拾える。逆に単語1つぶんの微変化は250画素を
      95              : // 下回ると見逃す。文字単位の変化まで見たいならトレランスではなく専用の小さい golden を撮る。
      96              : //
      97              : // この係数を緩めすぎると実変化が静かに素通りする。上限の目安は2行ラベル変更 570画素の
      98              : // 半分、係数0.34。TestToleranceForSize がこの上限を守らせる。
      99              : // 締める判断は推測でなく実測で行う。比較時に差分画素数をログへ出しているので、
     100              : // CI を含む実行環境ごとの実マージンをそこから読める。
     101              : const noiseScale = 0.3
     102              : 
     103              : // toleranceForSize は画像のピクセル数からトレランス比率を算出する。
     104              : // ノイズ量はUIエッジに比例するため √面積 でスケーリングし、
     105              : // 小さい画像ほど高い比率、大きい画像ほど低い比率を返す
     106              : func toleranceForSize(width, height int) float64 {
     107            1 :         total := width * height
     108            1 :         if total <= 0 {
     109            1 :                 return 0
     110            1 :         }
     111            1 :         return noiseScale / math.Sqrt(float64(total))
     112              : }
     113              : 
     114              : // assertPNGGolden はPNGバイト列を name のゴールデン画像と比較する。golden は testdata/name.png。
     115              : // name はサブテスト名でなく明示的に渡す。t.Run のスラッシュがパスに混ざらず、保存先が平置きになる。
     116              : // 画像サイズからトレランスを自動算出し、小さい画像は寛容に、大きい画像は厳密に判定する。
     117              : // GOLDIE_UPDATE=1 のときはトレランスを見ず無条件に上書きする。トレランス内スキップは
     118              : // 実変化を隠すので、更新は手動で走らせたときに必ず反映させる
     119              : func assertPNGGolden(t *testing.T, name string, pngData []byte) {
     120            0 :         t.Helper()
     121            0 : 
     122            0 :         cfg, err := png.DecodeConfig(bytes.NewReader(pngData))
     123            0 :         require.NoError(t, err, "failed to decode PNG header")
     124            0 :         toleranceRatio := toleranceForSize(cfg.Width, cfg.Height)
     125            0 : 
     126            0 :         if isGoldieUpdate() {
     127            0 :                 g := newGoldie(t)
     128            0 :                 require.NoError(t, g.Update(t, name, pngData))
     129            0 :                 t.Logf("updated golden image: %s", g.GoldenFileName(t, name))
     130            0 :                 return
     131            0 :         }
     132              : 
     133              :         // 直近の比較の差分画素数。EqualFn が書き、失敗時の DiffFn が報告へ使う
     134            0 :         var lastDiff, lastAllowed int
     135            0 :         g := newGoldie(t,
     136            0 :                 goldie.WithEqualFn(pngPixelEqualFn(t, toleranceRatio, &lastDiff, &lastAllowed)),
     137            0 :                 goldie.WithDiffFn(func(_, _ string) string {
     138            0 :                         return fmt.Sprintf(
     139            0 :                                 "pixel diff exceeds tolerance: image %dx%d, diff %d px > allowed %d px",
     140            0 :                                 cfg.Width, cfg.Height, lastDiff, lastAllowed,
     141            0 :                         )
     142            0 :                 }),
     143              :         )
     144            0 :         g.Assert(t, name, pngData)
     145              : }
     146              : 
     147              : // isGoldieUpdate は GOLDIE_UPDATE が有効かどうかを返す
     148              : func isGoldieUpdate() bool {
     149            1 :         switch os.Getenv("GOLDIE_UPDATE") {
     150              :         case "1", "true", "t":
     151            1 :                 return true
     152              :         default:
     153            1 :                 return false
     154              :         }
     155              : }
     156              : 
     157              : // newGoldie はgoldieインスタンスを生成する。サフィックスを.pngにして画像ファイルとして扱う
     158              : func newGoldie(t *testing.T, opts ...goldie.Option) *goldie.Goldie {
     159            0 :         t.Helper()
     160            0 :         all := make([]goldie.Option, 0, 1+len(opts))
     161            0 :         all = append(all, goldie.WithNameSuffix(".png"))
     162            0 :         all = append(all, opts...)
     163            0 :         return goldie.New(t, all...)
     164            0 : }
     165              : 
     166              : // channelTolerance16 は1チャンネルあたり許容する差分。RGBA() が返す16bit値(0..65535)で表す。
     167              : // 0x101 は color の RGBA() が8bit階調を16bit空間へ拡張する係数(v*0x101)。8bitで16階調ぶん許容する。
     168              : // フォントのアンチエイリアスはグリフ境界で数階調ゆれるが、これを差分として数えない。文字や色の
     169              : // 実変化はアルファが 0↔全開など全階調規模で動くので取りこぼさない。差分の「数」だけでなく
     170              : // 「大きさ」も見る二段トレランスになり、AAノイズ由来のフレークを防ぐ。
     171              : //
     172              : // 限界: 広域に及ぶ中振幅の変化、たとえば背景色の微変更は、各画素が許容振幅内に収まると見逃す。
     173              : // メニュー系の現状の用途では実害ないが、複雑な画面へ転用するときはこの盲点に注意する。
     174              : const channelTolerance16 = 16 * 0x101
     175              : 
     176              : // absDiffU32 は2値の差の絶対値を返す
     177              : func absDiffU32(a, b uint32) uint32 {
     178            1 :         if a > b {
     179            1 :                 return a - b
     180            1 :         }
     181            1 :         return b - a
     182              : }
     183              : 
     184              : // pngPixelEqualFn は2つのPNGバイト列をピクセル単位で比較する。
     185              : // toleranceRatio で許容する差分ピクセル比率を、channelTolerance16 で1画素内の許容振幅を指定する。
     186              : // どのチャンネルも許容振幅以内なら同一画素とみなし、振幅を超えた画素数が比率を超えたら不一致とする。
     187              : // 差分画素数は成否によらずログへ出す。実行環境ごとの実マージンを可視化し、
     188              : // トレランスを締める判断の実測根拠にする
     189              : func pngPixelEqualFn(t *testing.T, toleranceRatio float64, lastDiff, lastAllowed *int) goldie.EqualFn {
     190            1 :         t.Helper()
     191            1 :         return func(actual, expected []byte) bool {
     192            1 :                 actualImg, err := png.Decode(bytes.NewReader(actual))
     193            1 :                 if err != nil {
     194            1 :                         return false
     195            1 :                 }
     196            1 :                 expectedImg, err := png.Decode(bytes.NewReader(expected))
     197            1 :                 if err != nil {
     198            1 :                         return false
     199            1 :                 }
     200              : 
     201            1 :                 eb := expectedImg.Bounds()
     202            1 :                 ab := actualImg.Bounds()
     203            1 :                 if eb.Dx() != ab.Dx() || eb.Dy() != ab.Dy() {
     204            1 :                         return false
     205            1 :                 }
     206              : 
     207            1 :                 totalPixels := eb.Dx() * eb.Dy()
     208            1 :                 maxAllowed := int(float64(totalPixels) * toleranceRatio)
     209            1 :                 diffCount := 0
     210            1 :                 for y := eb.Min.Y; y < eb.Max.Y; y++ {
     211            1 :                         for x := eb.Min.X; x < eb.Max.X; x++ {
     212            1 :                                 er, eg, ebl, ea := expectedImg.At(x, y).RGBA()
     213            1 :                                 ar, ag, abl, aa := actualImg.At(x, y).RGBA()
     214            1 :                                 if absDiffU32(er, ar) > channelTolerance16 ||
     215            1 :                                         absDiffU32(eg, ag) > channelTolerance16 ||
     216            1 :                                         absDiffU32(ebl, abl) > channelTolerance16 ||
     217            1 :                                         absDiffU32(ea, aa) > channelTolerance16 {
     218            1 :                                         diffCount++
     219            1 :                                 }
     220              :                         }
     221              :                 }
     222            1 :                 *lastDiff, *lastAllowed = diffCount, maxAllowed
     223            1 :                 if diffCount > 0 {
     224            1 :                         t.Logf("golden margin: diff %d px / allowed %d px", diffCount, maxAllowed)
     225            1 :                 }
     226            1 :                 return diffCount <= maxAllowed
     227              :         }
     228              : }
        

Generated by: LCOV version 2.0-1