本記事はアジアクエスト - アジアクエスト Advent Calendar 2025 の記事です。
Laravel Duskを利用したブラウザテスト
Laravelにおいて、バックエンドのテストはPHPUnitを利用して「ユニットテスト」「機能テスト」を行うことができます。
しかし、ユーザーが実際に触れるフロントエンドの挙動、特にJavaScriptが絡む動的な操作や見た目の崩れを検証するには、ブラウザを操作するテストが必要です。
そんなテストを行えるパッケージが、Laravelの公式パッケージであるLaravel Duskです。
Laravel Duskは、ブラウザ操作を自動化し、ユーザー目線でのテスト（エンドツーエンドテスト）を実現します。
1. Laravel Duskとは何か？
Laravel Duskは、Googleのヘッドレスブラウザ（画面を持たないChrome/Chromium）であるChromeDriverを利用し、実際のブラウザ上でアプリケーションを操作します。
以下がLaravel Duskの特徴をまとめたものになります。
- 簡易な環境構築
- Laravelプロジェクトに組み込むだけで動作し、テスト実行時に自動でChromeDriverを起動するため、複雑な環境設定が不要
- エンドツーエンド (E2E) テスト
- ユーザーの操作（ログイン、フォーム送信、クリック、画面遷移など）を最初から最後までシミュレーションし、アプリケーション全体が期待通りに連携して動作するかのチェック
- JavaScriptの実行
- PHPUnitの機能テストでは検証できない、Vue.jsやReactなどのJavaScriptフレームワークによる動的なDOM操作や非同期通信の動作チェック
2. 環境構築とテストファイルの作成
導入手順
Laravel DuskはLaravel標準のパッケージではないため、Composerを使ってインストールする必要があります。
また、Laravel Duskは開発時のみ必要なため、--devオプションを付けてインストールします。
composer require laravel/dusk --dev
php artisan dusk:install
テストファイルの作成
テストファイルはtests/Browserディレクトリに配置されます。
テストファイルは以下のコマンドで自動作成が可能です。
php artisan dusk:make RegistrationTest
3. Duskテストの記述の基本
Duskのテストは、$this->browse(Closure $callback)ヘルパー内で記述します。
$callbackに渡される$browserオブジェクトを通じて、ブラウザを操作します。
基本的な操作チェーン
以下の例では、新しいユーザー登録の流れをシミュレーションしています。
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;
class RegistrationTest extends DuskTestCase
{
public function testNewUserCanRegister(): void
{
$this->browse(function (Browser $browser) {
$browser->visit('/register') // 1. 登録ページにアクセス
->type('name', 'Dusk User') // 2. nameフィールドに入力
->type('email', 'dusk@example.com')
->type('password', 'secret')
->type('password_confirmation', 'secret')
->press('Register') // 3. "Register"ボタンをクリック
->assertPathIs('/home') // 4. /homeにリダイレクトされたことのチェック
->assertSee('Welcome, Dusk User'); // 5. 成功メッセージが表示されたことのチェック
});
}
}
4. テストのための高度な機能
A. 認証済みユーザーとしてのテスト
既にログインしている状態でテストを開始したい場合、loginAs()メソッドを使用します。
これにより、テスト実行前に自動的にセッションが確立され、ログインした状態でのテストが行えます。
$this->browse(function (Browser $browser) use ($user) {
// 事前に作成したユーザーでログインした状態からテストを開始
$browser->loginAs($user)
->visit('/settings')
->assertSee('Account Settings');
});
B. 待機（Waiting）
JavaScriptによる遅延ロードや非同期処理の結果を待つために、待機の操作が非常に重要です。Duskは様々な待機メソッドを提供しています。
| メソッド | 概 |
|---|---|
| $browser->waitFor('#element-id') | 指定した要素が表示されるまで待機 |
| $browser->waitForText('Loading Complete') | 指定したテキストが表示されるまで待機 |
| $browser->pause(1000) | 指定時間（ミリ秒）だけ処理を停止 (最終手段として使用) |
// 非同期でデータがロードされ、リストが表示されるのを待つ
$browser->visit('/items')
->waitFor('#item-list')
->assertSee('First Item');
C. ページオブジェクト (Page Objects) パターン
テストコードが複雑化するのを防ぐため、Laravel DuskはPage Objectsパターンを推奨しています。
ページオブジェクトの作成
ページオブジェクトは以下コマンドで自動作成が可能です。
php artisan dusk:page Home
ページオブジェクトでは、
ページ内の要素セレクタや、そのページ固有の操作をメソッドとして定義します。
// resources/views/vendor/dusk/pages/Home.php
class Home extends Page
{
// このページのURLパスを定義
public function url(): string
{
return '/home';
}
// ページ内で使用するセレクタを定義
public function selector(): array
{
return [
'@logoutButton' => 'button[name="logout"]',
];
}
}
テストで実際に利用する例は以下になり、テストコードが大幅に簡略化されます。
$this->browse(function (Browser $browser) {
$browser->visit(new Home) // Page Objectを利用してアクセス
->click('@logoutButton') // セレクタ名を指定
->assertGuest();
});
5. テストの実行
ターミナルで実行します。
Laravel Duskはデフォルトでヘッドレスモード（ブラウザが画面に表示されない）で実行されます。
php artisan dusk
デバッグに便利な実行オプション
テスト中にブラウザの動きを実際に確認したい場合、--unheadlessオプションを付けます。
php artisan dusk --unheadless
また、テストが失敗した場合、Duskは失敗時の画面のスクリーンショットをtests/Browser/screenshotsディレクトリに自動で保存してくれるため、デバッグが容易です。
まとめ
Laravel Duskは、LaravelアプリケーションのUXを保証するためのテストツールです。
ブラウザを自動で操作し、複雑なフロントエンドの挙動を検証することで、アプリケーションの品質を保証できるようになります。
質の高い実装を行うため、Laravel Duskを導入し、テスト駆動開発（TDD）の精神をフロントエンドにも広げてみませんか？