Nexus StudioQAでの視覚的回帰テスト。
Nexus StudioQAの視覚的回帰テストは、各実行の画面画像を承認済みの基準画像と比較します。--visualを指定した初回の実行で基準画像を作成します。以降の実行では、アンチエイリアス処理された輪郭を除いて変化した画素を数え、変化が許容値を超えた場合に差分画像を保存します。既定では、回帰は記録されますが、テストは不合格になりません。
執筆: Verdict System LLCのNexus StudioQAチーム。
最終更新日: .
各実行で比較するもの
検査箇所は2種類あり、それぞれに許容値があります。これは、回帰と判定されるまでに差異が許される画素の割合です。
| 検査箇所 | 撮影対象 | 既定の許容値 |
|---|---|---|
| ページ全体 | テスト終了時に撮影され、baselineという名前で保存される表示領域の画面画像。 | 画素の1.0% (NEXUS_VISUAL_THRESHOLD) |
| 要素 | テスト内でvisualCheck(page, 'cart-total', page.locator('#cart-total'))を使って指定する単一の要素。 | 画素の0.1% (NEXUS_VISUAL_ELEMENT_THRESHOLD) |
変化の判定方法
基準画像はブラウザーとプラットフォームごとに保存
基準画像はプロジェクトフォルダー内の
visual-baselines/<browser>@<platform>/に保存されるため、コードと一緒にバージョン管理できます。フォントやアンチエイリアス処理が異なるため、Windowsの画像がLinuxの画像と比較されることはありません。基準画像がないブラウザーとプラットフォームの組み合わせでは、専用の基準画像が作成されます。アンチエイリアス処理された輪郭は集計対象外
輪郭の色の再混合だけが原因で変化した画素は、差分画像で琥珀色に表示され、集計から除外されます。色成分の差が10以上ある画素は変化したとみなされます。この値はNEXUS_VISUAL_PIXEL_TOLERANCEで0から255の範囲に変更できます。
画像が安定するまで再撮影
連続する2枚がバイト単位で一致するまで、最大3回撮影します。安定しないページは、そのまま基準画像になるのではなく、不安定として報告されます。
サイズが違っても引き伸ばさない
2枚の画像は左上をそろえ、共通する領域を元のサイズで比較します。重ならない領域は差異として数えます。
実行されなかった検査は不合格
画像がない場合やネイティブ画像ライブラリがインストールされていない場合など, 比較を実行できないときは, 厳密モードの設定にかかわらずテストは失敗します. 実行されなかったチェックが合格として報告されることはありません.
重要な設定
いずれもStudioのビジュアル回帰画面にあり, 既定値は以下のとおりです.
| 設定 | 既定 | 主な機能 |
|---|---|---|
| 実行のたびにピクセルを比較 | オフ | すべての実行で比較を有効にします. --visualを指定すると, その実行でのみ有効になります. |
| 回帰があればテストを失敗にする | オフ | NEXUS_VISUAL_STRICT=trueの場合, ピクセルの変化が許容値を超えるとテストは失敗します. 無効の場合, 回帰は記録されますが, テストの判定は変わりません. |
| すべての画像でマスクする対象 | なし | 時計や広告など, すべての画像で塗りつぶす対象を指定するCSSセレクター (NEXUS_VISUAL_MASK). |
| 保持する回帰フォルダー数 | 10 | テストとチェックポイントごとに保持する最新フォルダーの数 (NEXUS_VISUAL_REGRESSION_RETAIN). |
確認して承認するもの
各回帰は, 関連ファイルとともにvisual-regressionに保存されます. Studioでは, 同じチェックポイントの過去の実行と並べて, 並列表示, スワイプ, 差分, 交互表示の4つの表示方法で確認できます.
| ファイル | 概要 |
|---|---|
baseline.png | 承認済みの画像. |
current.png | 今回の実行の画像. |
diff.png | 赤は変更された画素、黄褐色は無視されたアンチエイリアス、灰色は変更なし。 |
visual-report.md | 数値をプレーンテキストで記録したもの. |
result.json | 同じ結果をデータとして記録したもの. |
ピクセル比較では判断できないこと
ピクセルだけでは意図したデザイン変更と不具合を区別できないため, 各変更は人が承認します. Studioのこの変更を承認で1つのチェックポイントの画像を置き換えられます. コマンドラインではnexus baseline --update <TC_ID>で同じ操作ができます. 時計, 広告, アバターなど自動で変化するものはマスクする必要があります. そうしないと, 比較のたびに差分が検出され続けます.
よくある質問
ビジュアル回帰があるとテストは失敗しますか?
既定では失敗しません. 回帰は記録されますが, テストの判定は変わりません.
NEXUS_VISUAL_STRICTを有効にすると, 許容値を超える回帰があった場合にテストが失敗します.OSごとに基準画像があるのはなぜですか?
同じページでも, Windows, Linux, macOSではフォント, アンチエイリアス, スクロールバーの描画がわずかに異なります. OSをまたいで比較すると描画処理の違いだけでも変更として報告されるため, ブラウザーとプラットフォームごとに基準画像を保持します.
時計や広告が原因でチェックが失敗しないようにするには?
ビジュアル設定でCSSセレクターを指定してマスクするか, ページ内の確認したい部分に要素チェックポイントを設定します. 要素チェックポイントの許容値はページ全体の10分の1なので, 動く広告に影響されず厳密に確認できます.
基準画像はどこに保存されますか?
コードと一緒にコミットできるよう, 証跡フォルダーではなくプロジェクトフォルダー内の
visual-baselinesに保存されます. 回帰の差分は実行結果として, 証跡フォルダー内のvisual-regressionに保存されます.