{"id":625,"date":"2025-09-02T11:57:09","date_gmt":"2025-09-02T11:57:09","guid":{"rendered":"https:\/\/1v0.net\/blog\/?p=625"},"modified":"2025-09-02T20:05:14","modified_gmt":"2025-09-02T20:05:14","slug":"how-to-use-laravel-dusk-for-browser-testing","status":"publish","type":"post","link":"https:\/\/1v0.net\/blog\/how-to-use-laravel-dusk-for-browser-testing\/","title":{"rendered":"How to Use Laravel Dusk for Browser Testing"},"content":{"rendered":"\n

End-to-end browser testing ensures that your application works exactly as a user would experience it. Laravel Dusk provides a simple API to automate browser actions like clicking links, filling forms, and asserting page content \u2014 all without writing raw Selenium code. In this article, we\u2019ll set up Dusk, write real tests for authentication and forms, handle JavaScript interactions, capture screenshots and logs, and explore best practices for organizing browser tests in large projects.<\/p>\n\n\n\n

<\/div>\n\n\n\n

Installing and Setting Up Laravel Dusk<\/strong><\/h2>\n\n\n
composer require --dev laravel\/dusk\nphp artisan dusk:install<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
After installation, Dusk creates a tests\/Browser<\/code> directory with example tests, a DuskTestCase.php<\/code> base class, and updates your phpunit.xml<\/code> to include the Dusk environment. Run Dusk tests with php artisan dusk<\/code>. The package ships with a bundled ChromeDriver binary for headless or full-browser testing.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Writing Your First Dusk Test<\/strong><\/h2>\n\n\n
\/\/ tests\/Browser\/ExampleTest.php<\/span>\nnamespace<\/span> Tests<\/span>\\Browser<\/span>;\n\nuse<\/span> Laravel<\/span>\\Dusk<\/span>\\Browser<\/span>;\nuse<\/span> Tests<\/span>\\DuskTestCase<\/span>;\n\nclass<\/span> ExampleTest<\/span> extends<\/span> DuskTestCase<\/span>\n<\/span>{\n    public<\/span> function<\/span> test_homepage_loads<\/span>()<\/span>: void<\/span>\n    <\/span>{\n        $this<\/span>->browse(function<\/span> (Browser $browser)<\/span> <\/span>{\n            $browser->visit('\/'<\/span>)\n                ->assertSee('Welcome'<\/span>)\n                ->assertTitleContains('MyApp'<\/span>);\n        });\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This simple test checks that the homepage loads, the word \u201cWelcome\u201d is visible, and the page title contains \u201cMyApp.\u201d Dusk uses a fluent API to chain actions and assertions.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Testing Authentication Flows<\/strong><\/h2>\n\n\n
\/\/ tests\/Browser\/LoginTest.php<\/span>\nnamespace<\/span> Tests<\/span>\\Browser<\/span>;\n\nuse<\/span> App<\/span>\\Models<\/span>\\User<\/span>;\nuse<\/span> Laravel<\/span>\\Dusk<\/span>\\Browser<\/span>;\nuse<\/span> Tests<\/span>\\DuskTestCase<\/span>;\n\nclass<\/span> LoginTest<\/span> extends<\/span> DuskTestCase<\/span>\n<\/span>{\n    public<\/span> function<\/span> test_user_can_login<\/span>()<\/span>: void<\/span>\n    <\/span>{\n        $user = User::factory()->create([\n            'email'<\/span> => 'dusk@example.com'<\/span>,\n            'password'<\/span> => bcrypt('secret'<\/span>),\n        ]);\n\n        $this<\/span>->browse(function<\/span> (Browser $browser)<\/span> use<\/span> ($user)<\/span> <\/span>{\n            $browser->visit('\/login'<\/span>)\n                ->type('email'<\/span>, $user->email)\n                ->type('password'<\/span>, 'secret'<\/span>)\n                ->press('Login'<\/span>)\n                ->assertPathIs('\/dashboard'<\/span>)\n                ->assertSee($user->name);\n        });\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This Dusk test creates a user with a factory, fills in the login form, presses the login button, and verifies redirection to the dashboard with the user\u2019s name visible. This mimics the exact user workflow in the browser.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Handling JavaScript and Vue\/React Components<\/strong><\/h2>\n\n\n
$this<\/span>->browse(function<\/span> (Browser $browser)<\/span> <\/span>{\n    $browser->visit('\/posts\/create'<\/span>)\n        ->type('title'<\/span>, 'Dusk Post'<\/span>)\n        ->type('content'<\/span>, 'Testing with Dusk.'<\/span>)\n        ->check('published'<\/span>)\n        ->click('@save-button'<\/span>) \/\/ using dusk selectors<\/span>\n        ->waitForText('Post created'<\/span>)\n        ->assertSee('Dusk Post'<\/span>);\n});<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Dusk works seamlessly with JavaScript-heavy UIs built in Vue or React. Use waitForText<\/code>, waitFor<\/code>, and @dusk<\/code> selectors in Blade to target specific elements: <button dusk=\"save-button\">Save<\/button><\/code>. This ensures reliable tests even with dynamic content.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Capturing Screenshots and Console Logs<\/strong><\/h2>\n\n\n\n
Debugging browser tests is easier when you can see what happened at failure time. Laravel Dusk automatically captures screenshots on failure and stores them in tests\/Browser\/screenshots<\/code>. You can also capture them manually or store console logs for deeper insights.<\/p>\n\n\n\n
Manual Screenshots<\/strong><\/h3>\n\n\n
$this<\/span>->browse(function<\/span> (Browser $browser)<\/span> <\/span>{\n    $browser->visit('\/profile'<\/span>)\n        ->screenshot('profile-page'<\/span>); \/\/ saves to tests\/Browser\/screenshots<\/span>\n});<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Manual screenshots are useful in complex flows when you want to verify specific steps. Screenshots are stored as PNG files and can be viewed anytime after test runs.<\/p>\n\n\n\n
Console Logs<\/strong><\/h3>\n\n\n
$this<\/span>->browse(function<\/span> (Browser $browser)<\/span> <\/span>{\n    $browser->visit('\/dashboard'<\/span>);\n\n    $logs = $browser->driver->manage()->logs()->get('browser'<\/span>);\n    foreach<\/span> ($logs as<\/span> $log) {\n        dump($log->getMessage());\n    }\n});<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Accessing the underlying WebDriver allows you to retrieve JavaScript console logs. This is invaluable when diagnosing Vue\/React errors or failed AJAX calls that might not show in the DOM.<\/p>\n\n\n\n
Video Recording (Third-Party)<\/strong><\/h3>\n\n\n\n
While not built into Dusk, you can run Dusk inside a container with tools like Selenium Grid + ffmpeg to record videos of test runs. This is useful in CI pipelines for diagnosing flaky tests.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Organizing Browser Tests<\/strong><\/h2>\n\n\n\n
For large projects, structure your browser tests just like your app\u2019s domains:<\/p>\n\n\n
tests\/Browser\/\n\u251c\u2500 Auth\/\n\u2502  \u251c\u2500 LoginTest.php\n\u2502  \u251c\u2500 RegisterTest.php\n\u251c\u2500 Blog\/\n\u2502  \u251c\u2500 CreatePostTest.php\n\u2502  \u251c\u2500 EditPostTest.php\n\u251c\u2500 Components\/\n\u2502  \u251c\u2500 ModalTest.php\n\u2502  \u251c\u2500 PaginationTest.php<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
This folder structure keeps test coverage modular and easier to navigate. For reusable actions, create custom Page<\/code> objects with Dusk\u2019s php artisan dusk:page<\/code> command.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Database and Session Handling<\/strong><\/h2>\n\n\n
\/\/ Using DatabaseMigrations trait in a Dusk test<\/span>\nuse<\/span> Illuminate<\/span>\\Foundation<\/span>\\Testing<\/span>\\DatabaseMigrations<\/span>;\n\nclass<\/span> RegisterTest<\/span> extends<\/span> DuskTestCase<\/span>\n<\/span>{\n    use<\/span> DatabaseMigrations<\/span>;\n\n    public<\/span> function<\/span> test_user_can_register<\/span>()<\/span>: void<\/span>\n    <\/span>{\n        $this<\/span>->browse(function<\/span> (Browser $browser)<\/span> <\/span>{\n            $browser->visit('\/register'<\/span>)\n                ->type('name'<\/span>, 'Test User'<\/span>)\n                ->type('email'<\/span>, 'newuser@example.com'<\/span>)\n                ->type('password'<\/span>, 'password'<\/span>)\n                ->type('password_confirmation'<\/span>, 'password'<\/span>)\n                ->press('Register'<\/span>)\n                ->assertPathIs('\/dashboard'<\/span>);\n        });\n    }\n}<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Use DatabaseMigrations<\/code> or RefreshDatabase<\/code> traits in your Dusk tests to start with a clean database every time. This ensures tests don\u2019t bleed state across runs.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Running Tests in CI\/CD Pipelines<\/strong><\/h2>\n\n\n
# GitHub Actions example for running Laravel Dusk<\/span>\njobs:<\/span>\n  dusk-tests:<\/span>\n    runs-on:<\/span> ubuntu-latest<\/span>\n    services:<\/span>\n      mysql:<\/span>\n        image:<\/span> mysql:8<\/span>\n        env:<\/span>\n          MYSQL_DATABASE:<\/span> laravel<\/span>\n          MYSQL_ROOT_PASSWORD:<\/span> root<\/span>\n        ports:<\/span>\n          -<\/span> 3306<\/span>:3306<\/span>\n    steps:<\/span>\n      -<\/span> uses:<\/span> actions\/checkout@v4<\/span>\n      -<\/span> uses:<\/span> shivammathur\/setup-php@v2<\/span>\n        with:<\/span>\n          php-version:<\/span> '8.3'<\/span>\n      -<\/span> run:<\/span> composer<\/span> install<\/span>\n      -<\/span> run:<\/span> php<\/span> artisan<\/span> migrate<\/span>\n      -<\/span> run:<\/span> php<\/span> artisan<\/span> serve<\/span> &<\/span> # run server in background<\/span>\n      -<\/span> run:<\/span> php<\/span> artisan<\/span> dusk<\/span><\/code><\/span>Code language:<\/span> YAML<\/span> (<\/span>yaml<\/span>)<\/span><\/small><\/pre>\n\n\n
Dusk integrates with CI tools like GitHub Actions, GitLab CI, or Jenkins. Use headless mode for speed, or full browser mode when debugging with screenshots (--env=chrome<\/code>).<\/p>\n\n\n\n
<\/div>\n\n\n\n
Feature Tests vs Browser Tests<\/strong><\/h2>\n\n\n\n
Feature tests and Dusk browser tests often overlap, but they serve different purposes. Here\u2019s a comparison to decide when to use each:<\/p>\n\n\n\n
Aspect<\/th>Feature Tests<\/th>Dusk Browser Tests<\/th><\/tr><\/thead>
Scope<\/td>HTTP layer, controllers, database<\/td>Full browser (DOM, JS, CSS, user flows)<\/td><\/tr>
Speed<\/td>Fast (no browser overhead)<\/td>Slower (ChromeDriver involved)<\/td><\/tr>
Best for<\/td>API responses, redirects, auth rules<\/td>Forms, clicks, Vue\/React interactions<\/td><\/tr>
Setup<\/td>No extra drivers<\/td>Requires ChromeDriver \/ headless setup<\/td><\/tr>
Example<\/td>Assert JSON returned from API<\/td>Click \u201cLogin\u201d and check UI redirect<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
Use Feature Tests for logic and data integrity, and Browser Tests for validating the actual user experience in a browser.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Wrapping Up<\/strong><\/h2>\n\n\n\n
Laravel Dusk makes browser testing straightforward by combining expressive syntax with ChromeDriver. We covered installation, writing tests, handling authentication, JavaScript interactions, capturing screenshots, console logs, organizing test suites, database resets, and CI\/CD integration. With Dusk in place, you can confidently verify your app\u2019s real user experience and debug failures effectively.<\/p>\n\n\n\n
<\/div>\n\n\n\n
What\u2019s Next<\/strong><\/h2>\n\n\n\n
Expand your testing skills with these guides:<\/p>\n\n\n\n