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 : }
|