Playwright トラブルシューティング - Firefoxだけが動かない

Feb 4, 2026

現在開発中のAI画像ストックサイト『free-images』に、品質担保のためE2Eテストツールである Playwright を導入することにしました。

「モダンなツールだし、サクッと導入できるだろう」と高を括っていたのですが、Firefox環境でのみテストが落ちる という泥沼にハマりました。今回はそのトラブルシューティングの記録を残しておきます。WSL環境で開発している方の参考になれば幸いです。

最初のつまずき：謎の Syntax Error

まずは公式ドキュメント通りにテストコード (tests/home.spec.ts) を書き、実行してみました。

import { test, expect } from '@playwright/test';

test.describe('トップページ（ゲスト表示）のテスト', () => {
  test.beforeEach(async ({ page }) => {
    await page.goto('/ja');
  });
  // ...各テストケース
});

しかし、実行すると即座にエラー。

Error: Playwright Test did not expect test.describe() to be called here.

構文は合っているはずなのに、「ここで describe を呼ぶな」と怒られます。

よくよくエラーログを見ると、「You have two different versions of @playwright/test」という不穏なメッセージが。

原因：npmとpnpmの混ぜるな危険

pnpm-lock.yaml があるのに、手癖で npm install などを実行してしまったため、package-lock.json も生成されていたのです。

これにより、node_modules 内でバージョンの競合が起き、Playwrightが正しく動作していませんでした。

解決策：

環境をクリーンにして、パッケージマネージャーを pnpm に統一しました。

rm package-lock.json  # 不要なロックファイルを削除
rm -rf node_modules   # 既存のモジュールを全削除
pnpm store prune      # ストアの整合性を確認
pnpm install          # 再インストール

これで構文エラーは解消。Chrome (Chromium) でのテストはパスするようになりました。「よし、これで完了！」と思った矢先、本当の敵が現れます。

Firefoxだけが起動しない

クロスブラウザテストのため、Firefoxを含めて実行すると…

npx playwright test tests/home.spec.ts --project=firefox --headed

Chromeは通るのに、Firefoxだけが全滅です。

エラー内容

Error: browserType.launch: ENOENT: no such file or directory, stat '/home/indigo/.cache/ms-playwright/firefox-1495/firefox/lock'

ENOENT (Error NO ENTry)、つまり「ファイルがない」と言っています。パスを見ると ~/.cache/ms-playwright/… という、Playwrightがブラウザのバイナリを管理しているディレクトリを指していました。

なぜ消えた？ node_modules を再インストールした際、テストランナー自体は入りましたが、ブラウザ本体（Firefoxバイナリ）のリンクや実体がおかしくなっていたようです。また、WSL (Ubuntu) 環境特有のライブラリ不足も疑われました。

解決策：キャッシュの完全削除と再インストール

中途半端に修復しようとせず、Playwrightのブラウザキャッシュを一度「無」にしてから入れ直すのが最短ルートでした。

キャッシュフォルダを爆破する壊れている可能性のある既存のブラウザデータを手動で削除します。

rm -rf ~/.cache/ms-playwright

ブラウザと依存関係の再インストールただ install するだけでなく、install-deps も実行するのがポイントです。特にWSL環境では、Firefoxを動かすためのシステムライブラリ（GTKやdbus関連など）が不足していることがよくあります。

# ブラウザバイナリのダウンロード
npx playwright install

# システム依存ライブラリのインストール（sudo権限が必要になる場合あり）
npx playwright install-deps

これを実行すると、Ubuntu側で必要なパッケージ（libgtk-3-0 や libdbus-glib-1-2 など）も自動でチェックしてインストールしてくれます。

テスト成功再度Firefoxでテストを実行。

npx playwright test tests/home.spec.ts --project=firefox

無事、キツネのアイコンとともにブラウザが立ち上がり、テストがオールグリーンになりました！

まとめ

今回の教訓は以下の3点です。

ロックファイルは一つに絞る: npm と pnpm を混在させると、特にバイナリを扱うライブラリ（PlaywrightやPrismaなど）で整合性が壊れやすい。
Playwrightのブラウザは node_modules 外にある: npm install し直しただけではブラウザ本体は直らない。~/.cache/ms-playwright を疑うべし。
WSLユーザーは install-deps を忘れずに: Linux環境ではブラウザを動かすためのOSレベルの依存関係が必須。

E2Eテストは環境構築でハマりがちですが、一度整えば「寝ている間にバグを見つけてくれる」頼もしい相棒になります。めげずに整備していきましょう。