目次
- はじめに
- 環境
- なぜPlaywrightをWSL側へ入れたのか
- コマンドを実行するディレクトリ
- initializerを使わず手動で導入する
- Playwright TestとTypeScriptを追加する
- npm install scriptを確認する
- Chromiumだけをインストールする
- ChromiumのOS依存パッケージを導入する
- Playwrightの導入は3層に分かれる
- バージョンを確認する
- まとめ
- 公式一次情報
- 関連記事
はじめに
LaravelでPHPUnitのFeature Testを書いていても、実際のブラウザでなければ確認しにくい動作があります。
今回開発している映画レビューアプリでは、特に次のような確認が手動作業として残っていました。
- JavaScriptによるモーダルの開閉
- 初期フォーカス
-
Tab/Shift + Tabによるフォーカス循環 -
EscapeキーによるモーダルClose - Close後に起動元へフォーカスが戻ること
そこで、既存のPHPUnitを置き換えるのではなく、実ブラウザでなければ確認しづらい部分をPlaywrightに担当させる方針でブラウザテスト基盤を追加しました。
この記事では、Laravel 13 + WSL + Laravel Sailで構築している既存プロジェクトへ、Playwright Testを最小構成で導入したところまでを振り返ります。
環境
導入時点の環境です。
PHP 8.4.24
Laravel 13.26.1
Node.js 24.19.0
npm 11.17.0
Playwright Test 1.62.1
TypeScript 7.0.2
WSL Ubuntu 24.04
Playwright / Node.js / npm / ChromiumはWSL側で管理し、Laravel SailのアプリケーションコンテナへPlaywrightやブラウザ本体を追加しない構成にしました。
なぜPlaywrightをWSL側へ入れたのか
今回の開発環境は、
Windows
├─ Docker Desktop
│ └─ Laravel Sailで起動するコンテナ
│ ├─ Laravel
│ └─ MySQL
│
└─ WSL2 / Ubuntu
├─ Node.js
├─ npm
├─ Playwright Test
├─ TypeScript
└─ Chromium
という構成です。
Docker DesktopはWindows側で動作し、WSL 2 Integrationを有効にすることで、Ubuntu側からDocker CLIを利用できます。
PlaywrightはNode.js上でテストを実行し、さらにChromiumなどのブラウザを起動します。
そのため今回は、
WSL
├─ Node.js
├─ npm
├─ Playwright Test
├─ TypeScript
└─ Chromium
Laravel Sail
├─ Laravel
└─ MySQL
という役割分担にしました。
SailのPHPコンテナへPlaywrightやブラウザ依存パッケージまで追加すると、Laravelを動かすためのコンテナとブラウザテスト実行環境の責務が混ざってしまいます。
そこで、Playwright runnerとChromiumはWSL側、LaravelアプリケーションはSail側という構成にしています。
コマンドを実行するディレクトリ
以降のPlaywright導入コマンドは、WSLのUbuntu上で、Laravelプロジェクトのルートディレクトリへ移動してから実行します。
今回の環境では次のディレクトリです。
cd ~/projects/review-app-laravel
ここには、Laravelのファイルとともに次のようなファイルがあります。
artisan
composer.json
package.json
package-lock.json
vite.config.js
確認する場合は、次のように現在地を確認できます。
pwd
今回の例では、
/home/<ユーザー名>/projects/review-app-laravel
のようなLaravelプロジェクトルートになっていればOKです。
注意
以降の
npm install、npm ls、npx playwright ...などは、WindowsのPowerShellやLaravel Sailコンテナ内ではなく、WSLのUbuntu上から実行します。
initializerを使わず手動で導入する
Playwright公式では、既存プロジェクトへの導入方法として次のinitializerが用意されています。
npm init playwright@latest
initializerを利用すると、Playwright設定ファイル、サンプルテスト、ブラウザのインストールなどをまとめて準備できます。
便利な一方、今回のLaravelプロジェクトにはすでに、
package.json
package-lock.json
GitHub Actions
PHPUnit tests/
などが存在しています。
そこで、自動生成される内容を後から整理するのではなく、必要なものだけを確認しながら追加するため、手動の最小導入を選びました。
Playwright TestとTypeScriptを追加する
先ほど確認したLaravelプロジェクトのルートで実行します。
npm install --save-dev @playwright/test typescript
追加後、導入されたバージョンを確認しました。
npm ls @playwright/test typescript --depth=0
導入時の結果です。
@playwright/test@1.62.1
typescript@7.0.2
package.jsonではどちらもdevDependenciesとして管理します。
Playwrightは本番アプリケーションを動かすための依存関係ではなく、開発・テスト時に利用するツールだからです。
npm install scriptを確認する
今回使用したnpmでは、依存パッケージが持つinstall scriptを確認するために次のコマンドを利用しました。
npm approve-scripts --allow-scripts-pending
このコマンドは、まだallowScriptsポリシーで確認されていないinstall scriptを一覧表示します。
--allow-scripts-pendingは確認専用のオプションで、この時点ではpackage.jsonを変更しません。
今回確認対象になったのは、
esbuild@0.25.12
でした。
esbuildはViteが利用している既存依存パッケージです。
内容を確認したうえで、次のように個別承認しました。
npm approve-scripts esbuild
その結果、package.jsonには次の設定が追加されました。
{
"allowScripts": {
"esbuild@0.25.12": true
}
}
ここで注意したいのは、今回導入時に使用したnpm 11.17.0では、approve-scriptsはinstall scriptの確認・許可方針をpackage.jsonへ記録するための仕組みであり、未承認scriptを直ちにすべてブロックするものではなかった点です。
今回の目的は、依存パッケージが実行するinstall scriptを把握し、確認したesbuild@0.25.12を許可対象として明示的に記録することでした。
Chromiumだけをインストールする
PlaywrightではChromium、Firefox、WebKitを利用できます。
しかし初期導入では、環境構築とテスト設計を単純にするためChromiumだけを対象にしました。
npx playwright install chromium
Playwrightでは、Playwright本体のバージョンに対応したブラウザバイナリを利用します。
そのため、npmパッケージとしてPlaywrightを導入することと、実際に操作するブラウザをインストールすることは別の作業です。
インストール済みブラウザは次のコマンドで確認できます。
npx playwright install --list
今回の環境では、Chromium関連として次のものが導入されました。
Chromium
Chrome Headless Shell
FFmpeg
ブラウザ本体はGitリポジトリ内ではなく、WSL側のcacheへ保存されます。
~/.cache/ms-playwright/
そのためChromium本体をGitへコミットする必要はありません。
ChromiumのOS依存パッケージを導入する
ブラウザバイナリだけではなく、Linux上でChromiumを動かすために必要なライブラリもあります。
Playwrightには、必要なOS依存関係をインストールするコマンドが用意されています。
npx playwright install-deps chromium
今回のWSL環境では管理者権限が必要だったため、実際には次のように実行しました。
sudo npx playwright install-deps chromium
Ubuntu側へフォント、NSS、X11関連ライブラリなどの依存パッケージが追加されました。
Playwright公式では、ブラウザ本体と依存関係をまとめて導入する次の方法も用意されています。
npx playwright install --with-deps chromium
今回は何が導入されるのか確認しやすくするため、browserとOS依存関係を分けて実行しました。
Playwrightの導入は3層に分かれる
ここまでを整理すると、Playwrightの導入では次の3つを分けて考えると理解しやすくなりました。
@playwright/test
↓
Node.js上で動くテストランナー
Chromium
↓
Playwrightが実際に操作するブラウザ
OS依存ライブラリ
↓
Ubuntu上でChromiumを動かすためのライブラリ
つまり、
npm install --save-dev @playwright/test
だけ成功しても、ブラウザテスト環境がすべて完成したわけではありません。
バージョンを確認する
最後にPlaywrightとTypeScriptのバージョンを確認しました。
npx playwright --version
npx tsc --version
今回の結果です。
Playwright 1.62.1
TypeScript 7.0.2
依存関係も確認します。
npm ls @playwright/test playwright playwright-core typescript --depth=1
Playwright Testから内部のplaywright、さらにplaywright-coreが利用される構成になっています。
まとめ
今回は、Laravel 13 + WSL環境の既存プロジェクトへ、Playwright Testを手動で最小導入しました。
今回までに準備したものは、
@playwright/test
TypeScript
Chromium
Chromium用OS依存ライブラリ
です。
この時点では、まだPlaywrightの設定ファイルやブラウザテストそのものは作成していませんでした。
次の記事では、Playwright用にTypeScript設定を作成した際に遭遇した、
Buffer
fs
stream
child_process
Symbol.asyncDispose
HTMLElement
Node
などの型エラーを追いながら、
@types/node
ESNext
DOM
NodeNext
がそれぞれ何のために必要だったのかを整理します。
公式一次情報
この記事の内容は、次の公式ドキュメントを確認しながら整理しています。
- Playwright - Installation
- Playwright - Browsers
- npm Docs - npm approve-scripts
- Docker Docs - Docker Desktop WSL 2 backend on Windows
参照日: 2026-09-06
Playwrightやnpmの仕様は更新されるため、実際に導入する際は最新版の公式ドキュメントも確認してください。