laravel-dusk

Laravel Dusk スキル

Laravel Dusk のブラウザー自動化とテストを包括的に支援し、Laravel アプリケーション向けの、表現力が高く使いやすいブラウザーテストの作成について専門的なガイダンスを提供します。

このスキルを使用するタイミング

次の場合に、このスキルを使用してください：

• Laravel のブラウザー自動化テストを作成またはデバッグする
• ユーザーインターフェースと JavaScript のインタラクションをテストする
• エンドツーエンド（E2E）テストのワークフローを実装する
• Laravel アプリケーションで自動 UI テストを設定する
• フォーム送信、認証フロー、ページ遷移のテストに取り組む
• ChromeDriver または代替のブラウザードライバーを設定する
• テストを整理するために Page Object パターンを使用する
• Vue.js コンポーネントをテストする、または JavaScript イベントを待機する
• ブラウザーテストの失敗やタイミングの問題をトラブルシューティングする

クイックリファレンス

1. 基本的なブラウザーテスト

public function testBasicExample(): void
{
    $this->browse(function (Browser $browser) {
        $browser->visit('/login')
            ->type('email', '[email protected]')
            ->type('password', 'password')
            ->press('Login')
            ->assertPathIs('/home');
    });
}

2. Dusk セレクターの使用（推奨）

<button dusk="login-button">Login</button>
<input dusk="email-input" name="email" />

// In your test - use @ prefix for dusk selectors
$browser->type('@email-input', '[email protected]')
    ->click('@login-button');

3. 複数のブラウザーのテスト

public function testMultiUserInteraction(): void
{
    $this->browse(function (Browser $first, Browser $second) {
        $first->loginAs(User::find(1))
            ->visit('/home');

        $second->loginAs(User::find(2))
            ->visit('/home');
    });
}

4. 要素の待機

// Wait for element to appear
$browser->waitFor('.modal')
    ->assertSee('Confirmation Required');

// Wait for text to appear
$browser->waitForText('Hello World');

// Wait for JavaScript condition
$browser->waitUntil('App.data.servers.length > 0');

// Wait when element is available
$browser->whenAvailable('.modal', function (Browser $modal) {
    $modal->assertSee('Delete Account')
        ->press('OK');
});

5. フォームの操作

// Text input
$browser->type('email', '[email protected]')
    ->append('notes', 'Additional text')
    ->clear('description');

// Dropdown selection
$browser->select('size', 'Large')
    ->select('categories', ['Art', 'Music']); // Multiple

// Checkboxes and radio buttons
$browser->check('terms')
    ->radio('gender', 'male');

// File upload
$browser->attach('photo', __DIR__.'/photos/profile.jpg');

6. Page Object パターン

// Generate page object
// php artisan dusk:page Login

// app/tests/Browser/Pages/Login.php
class Login extends Page
{
    public function url(): string
    {
        return '/login';
    }

    public function elements(): array
    {
        return [
            '@email' => 'input[name=email]',
            '@password' => 'input[name=password]',
            '@submit' => 'button[type=submit]',
        ];
    }

    public function login(Browser $browser, $email, $password): void
    {
        $browser->type('@email', $email)
            ->type('@password', $password)
            ->press('@submit');
    }
}

// Use in test
$browser->visit(new Login)
    ->login('[email protected]', 'password')
    ->assertPathIs('/dashboard');

7. ブラウザーマクロ（再利用可能なメソッド）

// In AppServiceProvider or DuskServiceProvider
use Laravel\Dusk\Browser;

Browser::macro('scrollToElement', function (string $element) {
    $this->script("$('html, body').animate({
        scrollTop: $('{$element}').offset().top
    }, 0);");

    return $this;
});

// Use in tests
$browser->scrollToElement('#footer')
    ->assertSee('Copyright 2024');

8. テストでのデータベース管理

use Illuminate\Foundation\Testing\DatabaseMigrations;
use Illuminate\Foundation\Testing\DatabaseTruncation;

class ExampleTest extends DuskTestCase
{
    // Option 1: Run migrations before each test (slower)
    use DatabaseMigrations;

    // Option 2: Truncate tables after first migration (faster)
    use DatabaseTruncation;

    // Exclude specific tables from truncation
    protected $exceptTables = ['migrations'];
}

9. JavaScript の実行

// Execute JavaScript
$browser->script('document.documentElement.scrollTop = 0');

// Get JavaScript return value
$path = $browser->script('return window.location.pathname');

// Wait for reload after action
$browser->waitForReload(function (Browser $browser) {
    $browser->press('Submit');
})->assertSee('Success');

10. よく使うアサーション

// Page assertions
$browser->assertPathIs('/dashboard')
    ->assertRouteIs('dashboard')
    ->assertTitle('Dashboard')
    ->assertSee('Welcome Back')
    ->assertDontSee('Error');

// Form assertions
$browser->assertInputValue('email', '[email protected]')
    ->assertChecked('remember')
    ->assertSelected('role', 'admin')
    ->assertEnabled('submit-button');

// Element assertions
$browser->assertVisible('.success-message')
    ->assertMissing('.error-alert')
    ->assertPresent('button[type=submit]');

// Authentication assertions
$browser->assertAuthenticated()
    ->assertAuthenticatedAs($user);

主な概念

Dusk セレクターと CSS セレクター

Dusk セレクター（推奨）は、UI の更新によって変わらない HTML の dusk 属性を使用します：

• CSS クラスや ID より安定しています
• テスト対象の要素を明示的に指定します
• テストでは @ プレフィックスを使用します：$browser->click('@submit-button')
• HTML に追加します：<button dusk="submit-button">送信</button>

CSS セレクターは変更の影響を受けやすいものの、必要になる場合もあります：

• .class-name、#id、div > button
• HTML の構造が変わると動作しなくなることがあります
• HTML を制御できない場合に使用します

待機方法

任意の時間だけ待つのではなく、常に明示的に待機してください：

• waitFor('.selector') - 要素が存在するまで待機します
• waitUntilMissing('.selector') - 要素が消えるまで待機します
• waitForText('text') - テキストが表示されるまで待機します
• waitUntil('condition') - JavaScript の条件が満たされるまで待機します
• whenAvailable('.selector', callback) - 要素が利用可能になったときにコールバックを実行します

Page Object

複雑なテストロジックをPage クラスに整理します：

• URL、アサーション、要素セレクターを定義します
• ページ固有の操作に再利用可能なメソッドを作成します
• テストの可読性と保守性を高めます
• 次のコマンドで生成します：php artisan dusk:page PageName

ブラウザーマクロ

よく使うパターンに対して再利用可能なブラウザーメソッドを定義します：

• サービスプロバイダーの boot() メソッドに登録します
• すべてのテストで使用できます
• 組み込みメソッドと同様にチェーンできます
• 例：スクロール、モーダルの操作、カスタムアサーション

リファレンスファイル

このスキルには、references/ 内に包括的なドキュメントが含まれています：

• other.md - 次の内容を網羅した Laravel Dusk の完全なドキュメント：
  • インストールと設定
  • ChromeDriver の管理
  • テストの生成と実行
  • ブラウザーの操作メソッド
  • フォーム処理とファイルアップロード
  • 待機方法とアサーション
  • Page Object と Component のパターン
  • CI/CD の統合例

次の情報が必要な場合は、リファレンスファイルを使用してください：

• 特定のメソッドに関する詳細な API ドキュメント
• 利用可能なアサーションの完全な一覧（70 以上）
• さまざまな環境向けの設定オプション
• iframe、JavaScript ダイアログ、キーボードマクロなどの高度なトピック

このスキルの活用

初心者向け

1. 基本的なテストから始める：シンプルな visit()、type()、press()、assertSee() メソッドを使用します
2. Dusk セレクターを使用する：安定したセレクターを使えるよう、HTML に dusk 属性を追加します
3. 待機方法を学ぶ：信頼性の高いテストを実現するため、pause() ではなく常に waitFor() を使用します
4. テストを実行する：php artisan dusk を実行して結果を確認します

中級ユーザー向け

1. ページオブジェクトを実装する：ページパターンを使って複雑なテストを整理します
2. データベーストレイトを使う：DatabaseMigrations または DatabaseTruncation を選択します
3. ブラウザマクロを作成する：よく使うワークフロー向けに再利用可能なメソッドを定義します
4. 認証をテストする：loginAs() を使ってログイン画面をスキップします
5. JavaScript に対応する：動的コンテンツや AJAX には waitUntil() を使います

上級ユーザー向け

1. 複数ブラウザでのテスト：複数のブラウザでリアルタイム機能をテストします
2. カスタム待機ロジック：複雑な条件には waitUsing() を使います
3. コンポーネントパターン：共通の UI 要素向けに再利用可能なコンポーネントを作成します
4. CI/CD との統合：GitHub Actions、Travis CI、その他のプラットフォームで Dusk を設定します
5. 代替ドライバー：Selenium Grid や ChromeDriver 以外のブラウザを設定します

ナビゲーションのヒント

• 簡単な例：一般的なパターンについては、上記のクイックリファレンスを確認してください
• メソッドのドキュメント：API リファレンス全体については、other.md を参照してください
• アサーション一覧：リファレンスファイルには、利用可能な 70 種類以上のアサーションがすべて記載されています
• 設定：環境設定とドライバーのオプションについては、リファレンスファイルを確認してください
• ベストプラクティス：リファレンスドキュメントの「ベストプラクティス」セクションを参照してください

インストールとセットアップ

# Install Laravel Dusk
composer require laravel/dusk --dev

# Run installation
php artisan dusk:install

# Update ChromeDriver
php artisan dusk:chrome-driver

# Make binaries executable (Unix)
chmod -R 0755 vendor/laravel/dusk/bin/

# Run tests
php artisan dusk

よく使うコマンド

# Generate new test
php artisan dusk:make LoginTest

# Generate page object
php artisan dusk:page Dashboard

# Generate component
php artisan dusk:component Modal

# Run all tests
php artisan dusk

# Run specific test
php artisan dusk tests/Browser/LoginTest.php

# Run failed tests only
php artisan dusk:fails

# Run with filter
php artisan dusk --group=authentication

# Update ChromeDriver
php artisan dusk:chrome-driver --detect

リソース

公式ドキュメント

• Laravel Dusk ドキュメント：https://laravel.com/docs/12.x/dusk
• API リファレンス：メソッド一覧全体については、references/other.md を参照してください

リファレンスファイルに記載されている一般的なパターン

リファレンスドキュメントには、以下が含まれています：

• 説明付きの 70 種類以上のアサーションメソッド
• フォーム操作 API 全体
• 待機方法とタイミングに関するベストプラクティス
• ページオブジェクトパターンの例
• ブラウザマクロの定義
• CI/CD 設定の例
• 環境別のテストセットアップ

ベストプラクティス

1. 安定性を高めるため、CSS クラスの代わりに Dusk セレクター（dusk 属性）を使います
2. 任意の pause() ではなく、waitFor() メソッドで明示的に待機します
3. 複雑なテストシナリオでは、ページオブジェクトを使って整理します
4. データベースの切り捨てを活用して、テストの実行を高速化します
5. 頻繁に繰り返す操作にはブラウザマクロを作成します
6. 特定のページ領域では、with() または elsewhere() を使ってセレクターの対象範囲を限定します
7. 実装の詳細ではなく、ユーザーの操作をテストします
8. loginAs() などの認証ショートカットを使って、ログインフローをスキップします
9. 失敗のデバッグには、screenshot() でスクリーンショットを撮影します
10. 関連するテストをグループ化し、--group フラグを使って対象を絞って実行します

トラブルシューティング

よくある問題

ChromeDriver のバージョン不一致：

php artisan dusk:chrome-driver --detect

要素が見つからない：

• 操作の前に waitFor('.selector') を使います
• 要素が iframe 内にあるか確認します
• ブラウザーの開発者ツールでセレクターを確認します

テストがランダムに失敗する：

• pause() を明示的な待機に置き換えます
• タイムアウトを延長します：waitFor('.selector', 10)
• JavaScript の条件には waitUntil() を使います

データベースの状態に関する問題：

• DatabaseTruncation トレイトを使います
• setUp() メソッドでデータをリセットします
• アプリケーションコード内のトランザクションを確認します

注意事項

• Laravel Dusk はデフォルトで ChromeDriver を使用します（Selenium／JDK は不要です）
• Selenium WebDriver プロトコルを介して、代替ブラウザをサポートします
• テストは tests/Browser ディレクトリに保存されます
• ページオブジェクトは tests/Browser/Pages に配置します
• 失敗時のスクリーンショットは tests/Browser/screenshots に保存されます
• デバッグ用のコンソールログは tests/Browser/console に保存されます