Docker で Laravel Dusk を利用する方法

docker-compose.yml には E2E テスト用の dusk サービス（Selenium Standalone Chrome）が含まれています。
本番開発用の webapp サービスとは分離されており、通常の docker compose up では起動しないよう profiles で制御しています。

Dusk サービスの起動

# Dusk プロファイルを有効にして起動
docker compose --profile dusk up -d dusk

# webapp と合わせて起動したい場合
docker compose --profile dusk up -d webapp dusk

webapp コンテナには既定で DUSK_DRIVER_URL=http://dusk:4444/wd/hub が設定されているため、Dusk テストを走らせる際は上記コマンドで Selenium を起動しておけばそのまま接続できます。

Dusk サービスの停止

docker compose --profile dusk stop dusk

または本体ごと停止する場合は docker compose down を実行してください。

ブラウザ画面の確認（VNC/noVNC）

• VNC クライアントで接続する場合: localhost:${DUSK_VNC_PORT:-5900} を指定します（パスワードなし）。
• ブラウザから確認したい場合: http://localhost:${DUSK_NOVNC_PORT:-7900} にアクセスすると noVNC 画面でブラウザ操作をライブ観察できます。

docker-compose.yml では各ポート番号を環境変数で上書き可能です。必要に応じて .env や docker compose 実行時に変更してください。

よくある質問

• なぜデフォルトで起動しないのか？
  Selenium イメージの取得やヘルスチェックに失敗すると webapp の起動まで阻害してしまうためです。必要なときだけ --profile dusk を指定することで、通常の開発フローへの影響を避けています。

• 任意のブラウザ設定を追加したい
  docker-compose.override.yml を作成し、dusk サービスに追加の環境変数やボリュームを上書きしてください。

特定クラスのブラウザテストを単独実行する手順

1. Selenium を起動
   docker compose --profile dusk up -d dusk
2. Dusk 用の環境変数を準備
   .env.dusk.local を作成し、必要な DUSK_* 設定を記述します（無ければ .env.dusk を利用）。
3. Dusk 用 Seeder の準備
   .env.dusk.local に DUSK_AUTO_MIGRATE=true と
   DUSK_SEEDERS="Database\\Seeders\\DatabaseSeeder,Database\\Seeders\\DuskPagesTableSeeder" を設定します。
   これにより Dusk 実行前に migrate:fresh とページシーダーが自動で適用され、実行順依存を解消できます。
4. 目的のテストクラスを実行
   php artisan dusk --filter=FormsPluginTest
   （--filter= にはクラス名やメソッド名のプレフィックスを指定できます。PHPUnit を直接使う場合は vendor/bin/phpunit -c phpunit.dusk.xml --filter=FormsPluginTest でも同様に実行可能です。）

• 画面を映したままデバッグしたい場合
  .env.dusk.local の DUSK_HEADLESS=false を設定し、Selenium コンテナの noVNC (http://localhost:${DUSK_NOVNC_PORT:-7900}) へアクセスしてください。

DUSK_* 環境変数

.env.example には Dusk 実行時に参照される設定値（コメントアウト済み）がまとまっています。
Laravel Dusk は php artisan dusk 実行時に、現在の APP_ENV（例: local）を用いて .env.dusk.{APP_ENV} を探し、見つかった場合はその内容を .env として読み込みます。したがってローカル開発では .env.dusk.local を用意すると、本番・開発用設定を汚さずに Dusk 専用の値を切り分けられます。該当するファイルが無ければフォールバックとして .env.dusk が利用されます。Docker で Selenium を使う場合は必要に応じて .env か .env.dusk.{APP_ENV} にコピーして有効化してください。

変数名	役割	既定値/補足
DUSK_DRIVER	使用する WebDriver 名。Selenium コンテナに接続する場合は selenium を指定します。	指定なし（ChromeDriver 直接接続時は空のままで問題ありません）
DUSK_DRIVER_URL	WebDriver の接続 URL。docker compose --profile dusk で起動した Selenium に合わせて http://dusk:4444/wd/hub を指定します。	未設定時は http://localhost:9515（ローカル ChromeDriver）
DUSK_HEADLESS	true でヘッドレス実行。UI を見ながらデバッグしたい場合は false にします。	true
DUSK_AUTO_MIGRATE	true にすると Dusk の初回起動前に php artisan migrate:fresh --force を実行します。テスト専用 DB を初期化したい場合に有効化してください。	false
DUSK_SEEDERS	DUSK_AUTO_MIGRATE と併用。カンマ区切りで Seeder クラスを指定すると migrate:fresh 後に順番に実行されます。例: Database\\Seeders\\DatabaseSeeder,Database\\Seeders\\DuskPagesTableSeeder	空文字
DUSK_NO_MANUAL_ALL	true でマニュアル生成をスキップ。スクリーンショットのみ取得したい場合に使用します。	未設定
DUSK_NO_API_TEST_ALL	true で Dusk 実行時に API テストを除外します。	未設定