Visual Regression Testing（VRT）をPlaywrightで導入する際に、toHaveScreenshot() メソッドで謎のエラーが発生しました。
正直なところ、このエラー原因を特定するのに時間がかかりました。最初は設定ミスかと思いましたが、実際にはPlaywrightの仕様に関連する問題でした。
こんな人におすすめ
この記事は以下のような方に役立ちます。
- PlaywrightでVRTを導入中の方
toHaveScreenshotエラーに遭遇して解決策を探している方- E2Eテストの環境構築を進めている方
目次
背景
Visual Regression Testing（VRT）をPlaywrightで導入する際に、toHaveScreenshot() メソッドで謎のエラーが発生した。
症状
Error: Screenshot name "home-full-page" must have '.png' extension
最初は home-full-page だったエラーメッセージが、snapshotPathTemplate を削除したら home-full-page-chromium-darwin に変化した。
個人的には、このエラーメッセージの変化に気づいたことで、原因特定の手がかりが得られました。
原因
Playwrightの仕様として、toHaveScreenshot() に渡す引数には .png 拡張子を含める必要がある。
※公式ドキュメントでは.png拡張子は任意となっていますが、実際に私の環境では必須であるというエラーが発生しました。バージョンや環境依存の可能性があります。
- Playwrightのデフォルト
snapshotPathTemplateは{projectName}と{platform}を自動付与する snapshotPathTemplateを明示的に設定しても、引数の検証は別に行われる{ext}プレースホルダーはファイルパス生成用であり、引数検証をバイパスしない
直し方
1. テストコードに .png 拡張子を追加
// ❌ NG
await expect(page).toHaveScreenshot('login-page')
// ✅ OK
await expect(page).toHaveScreenshot('login-page.png')
2. snapshotPathTemplate を明示的に設定
// playwright.vrt.config.ts
export default defineConfig({
snapshotDir: './e2e/vrt/__snapshots__',
// {projectName}/{platform} を除外してシンプルなパスに
snapshotPathTemplate: '{snapshotDir}/{testFilePath}/{arg}{ext}',
})
生成されるパス: e2e/vrt/__snapshots__/login.vrt.spec.ts/login-page.png
実際にこの設定を変更してみた結果、エラーが解消されました。
学び
- エラーメッセージの変化を観察する: エラーメッセージが変わったことでデフォルトテンプレートの存在に気づけた
- Playwrightの公式ドキュメントを確認:
toHaveScreenshot(['foo', 'bar', 'baz.png'])の例から.pngが必須と判明 - 引数検証とパス生成は別処理:
snapshotPathTemplateの設定だけでは引数検証をバイパスできない
確認手順
pnpm vrt:update-snapshotsでベースライン生成pnpm vrtで比較テストが通ることを確認- 生成されたファイルパスが想定通りか確認
まとめ
PlaywrightのtoHaveScreenshotで.png拡張子に関するエラーが発生した際の原因と解決方法を紹介しました。
実際に設定を変更してみた結果、.png拡張子を明示的に指定することでエラーが解消されました。また、snapshotPathTemplateを適切に設定することで、スナップショットファイルのパスをシンプルに整理できます。
VRTの導入時にこのエラーに遭遇した方は、ぜひ参考にしてみてください。
