本記事はアジアクエスト - アジアクエスト 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）の精神をフロントエンドにも広げてみませんか？