😎
WSL2でplaywrightのE2Eが固まる問題解消のベストプラクティスらしきものを発見した話

2025/10/07に公開
 はじめにWSL2でplaywrightのE2Eが、chromeはすんなり動くが

firefox、webkitで固まる問題があって

それが、特権モードがどうのとか、サンドボックスの許可がどうのとか

いろいろ、難しいこと書いてるけど。

 とりあえず、下記のシンプルな思考で動くみたいだと、わかったので、覚書としてここに残しておくことにした。そしたら、この問題で困ったら、この記事見たら一発、解決する可能性高しなので、覚書きしとく記事としたpackage.json

の

"scripts": {

で、

"e2e:headed": "playwright test --headed",

"e2e:headless": "xvfb-run -a playwright test"

},

を入れとく

xvfb-runというのが、DISPLAYとかの変数を0とかなしのような値にして

WSLgを動かすようなラッパーとのこと
playwright.config.ts

で、

headless: !!process.env.CI,

をしているところは
    // ＜特記事項＞
    // package.jsonのscriptsに記載してある通り、
    // "e2e:headed": "playwright test --headed",
    // "e2e:headless": "xvfb-run -a playwright test"
    // を記載しており、
    // npm run e2e:headed
    // でheadedモード、GUIあり
    // npm run e2e:headless
    // でheadlessモード、GUIなし
    // で動かすため、
    // ★ ここをコメントアウトする
    // さもなくば、process.env.CIでheadedか、headlessかが決まってしまう
    //**** /* Only on CI systems run the tests headless */
    //**** headless: !!process.env.CI,
  },
のようにコメントアウトしておく
そして、必ず
裏で、
npm run dev
してる状況で
npm run e2e:headed

で、GUIありで動かす
npm run e2e:headless

で、GUIなしで動かす
npm run dev

なしでも、仕組み上は、動くらしい

けど、仮に動いたとしても、すごい時間待たされる。それは使えない
npm run dev

を裏でしとけば、スンナリ動く
以上が、おれが書いた、テキトーな文章

実用性重視で、要る分だけ書いたから、一旦は、これでよしだけど。
おそらく、厳密性、欠いてると思うから
AIに、厳密性チェックさせて、いろいろ、指摘事項あったから

下記に、補足　としていくつか、貼っとくことにした

でも、↑の、元の文章は、直すのメンドイから、そのままにしとくことにした。
以上
補足

xvfb-run の正確な動作：xvfb-run は Xvfb（仮想Xサーバー）を起動し、その仮想ディスプレイに > DISPLAY=:<番号> を割り当ててからコマンドを実行します。WSLg のラッパーではありません

（実モニタにウィンドウは出ず、仮想画面に描画されます）。
補足

Playwright の headed / headless の切り替え：CLIには --headed はありますが

--headless フラグはありません（デフォルトが headless）。

この記事のように e2e:headed と e2e:headless を スクリプトで明示分離すると

誤作動を避けられます。playwright.config.ts の headless: !!process.env.CI

をコメントアウトしたのは、この“明示分離”を壊さないためです。
補足

なぜ dev を先に起動すると速いか：Playwright の webServer は

「URLが応答するまで待つ」設計です。Vite の初回起動（コールドスタート）が遅いと

“固まって見える”時間が生まれます。先に npm run dev を立てておけば

reuseExistingServer により即テスト開始になり、待ちが消えます。

timeout を伸ばすのも手ですが、“先起動”が一番体感が良いです。
補足

WSL2・GUIありを使う場合：WSLg（またはXサーバー）が有効なら --headed

で実画面にウィンドウが出ます。もし GUI 経路で詰まる場合でも、

xvfb-run は Linux ユーザー空間だけで完結するため、WSL2 でも安定して“見えない画面”に描画できます。
補足

セキュリティ面：ここでの解決策（npm run dev 先起動、xvfb-run 利用）は

OSやブラウザのサンドボックス設定を弱めません。テスト起動プロセスの範囲に閉じた変更で、

他のアプリやシステム全体のリスクを広げないのが利点です。
補足

他OSの動作感：macOS / Windows / ネイティブLinux でも、

プロジェクト規模が大きいと初回ビルド待ちが発生します。

ローカル開発ではdevサーバー先起動→再利用が広く行われています。

CIでは（GUIなしが基本のため）headless で webServer 自動起動を使うのが定番です。
はじめに

Discussion
