---
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)
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の導入時にこのエラーに遭遇した方は、ぜひ参考にしてみてください。
