Playwright toHaveScreenshotの.png拡張子問題を解決

--- title: "Playwright toHaveScreenshotの.png拡張子問題を解決" description: "PlaywrightでVRT導入時に遭遇する`toHaveScreenshot`のエラー原因と解決方法を解説。`.png`拡張子の指定方法や`snapshotPathTemplate`の設定例を紹介します。" created: "2025-12-15" status: "draft" platforms: wordpress: published: false url: "" published_date: "" tags: ["Playwright", "VRT", "Visual Regression Testing", "E2E", "TypeScript"] --- 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` 拡張子を追加 ```typescript // ❌ NG await expect(page).toHaveScreenshot('login-page') // ✅ OK await expect(page).toHaveScreenshot('login-page.png') ``` ### 2. `snapshotPathTemplate` を明示的に設定 ```typescript // 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` 実際にこの設定を変更してみた結果、エラーが解消されました。 ## 学び 1. **エラーメッセージの変化を観察する**: エラーメッセージが変わったことでデフォルトテンプレートの存在に気づけた 2. **Playwrightの公式ドキュメントを確認**: `toHaveScreenshot(['foo', 'bar', 'baz.png'])` の例から `.png` が必須と判明 3. **引数検証とパス生成は別処理**: `snapshotPathTemplate` の設定だけでは引数検証をバイパスできない ## 確認手順 1. `pnpm vrt:update-snapshots` でベースライン生成 2. `pnpm vrt` で比較テストが通ることを確認 3. 生成されたファイルパスが想定通りか確認 ## まとめ Playwrightの`toHaveScreenshot`で`.png`拡張子に関するエラーが発生した際の原因と解決方法を紹介しました。 実際に設定を変更してみた結果、`.png`拡張子を明示的に指定することでエラーが解消されました。また、`snapshotPathTemplate`を適切に設定することで、スナップショットファイルのパスをシンプルに整理できます。 VRTの導入時にこのエラーに遭遇した方は、ぜひ参考にしてみてください。 ## 参考リンク - [Playwright Test Snapshots](https://playwright.dev/docs/test-snapshots) - [snapshotPathTemplate Configuration](https://playwright.dev/docs/api/class-testproject#test-project-snapshot-path-template)

Error: Screenshot name "home-full-page" must have '.png' extension

// ❌ NG
await expect(page).toHaveScreenshot('login-page')

// ✅ OK
await expect(page).toHaveScreenshot('login-page.png')

// playwright.vrt.config.ts
export default defineConfig({
  snapshotDir: './e2e/vrt/__snapshots__',
  // {projectName}/{platform} を除外してシンプルなパスに
  snapshotPathTemplate: '{snapshotDir}/{testFilePath}/{arg}{ext}',
})