Documentation Index Fetch the complete documentation index at: https://kawax.biz/llms.txt
Use this file to discover all available pages before exploring further.
What is Laravel Dusk? Laravel Dusk is Laravel’s end-to-end browser testing tool.
By default, Dusk runs with a standalone ChromeDriver, so you do not need to install Selenium or a separate JDK for local use.
The official documentation notes that Pest 4 now includes browser testing and is recommended for new projects. Use Dusk when your project already relies on Dusk APIs or workflows.
Install Dusk Install Google Chrome, then add Dusk as a development dependency:
composer require laravel/dusk --dev php artisan dusk:install
If needed, install a ChromeDriver version that matches your local Chrome build:
php artisan dusk:chrome-driver --detect
Environment handling with .env.dusk.local Create a Dusk-specific environment file at your project root:
APP_URL =http://127.0.0.1:8000 DB_CONNECTION =mysql DB_DATABASE =app_testing DB_USERNAME =root DB_PASSWORD =root
When you run Dusk from the local environment, name it .env.dusk.local..env during the test run, then restores your original .env.
Write and run a basic browser test Generate a test, then run Dusk:
php artisan dusk:make LoginTest php artisan dusk
Rerun only the previously failed browser tests:
Core browser actions <? php namespace Tests\Browser ; use App\Models\ User ; use Laravel\Dusk\ Browser ; use Tests\ DuskTestCase ; class LoginTest extends DuskTestCase { public function test_user_can_login () : void { $user = User :: factory () -> create ([ 'email' => '[email protected] ' , ]); $this -> browse ( function ( Browser $browser ) use ( $user ) { $browser -> visit ( '/login' ) -> type ( 'email' , $user -> email ) -> type ( 'password' , 'password' ) -> press ( 'Login' ) -> assertPathIs ( '/dashboard' ) -> assertSee ( 'Dashboard' ); }); } }
You will use visit(), type(), press(), and assertSee() in most Dusk tests.
Do not use RefreshDatabase in Dusk tests. Follow the official guidance and use DatabaseMigrations or DatabaseTruncation to reset state between tests.
Use the page object pattern For reusable page flows, generate a page object:
php artisan dusk:page Login
Then define url() and elements() in tests/Browser/Pages/Login.php and reuse it in tests:
use Tests\Browser\Pages\ Login ; $browser -> visit ( new Login ) -> type ( '@email' , '[email protected] ' ) -> type ( '@password' , 'password' ) -> click ( '@submit' ) -> assertSee ( 'Dashboard' );
Capture screenshots and debug artifacts Use Dusk helpers to collect debugging output:
$browser -> screenshot ( 'login-failed' ); $browser -> responsiveScreenshots ( 'login-page' ); $browser -> screenshotElement ( '#login-form' , 'login-form' ); $browser -> storeConsoleLog ( 'login-console' );
Screenshots: tests/Browser/screenshots
Console logs: tests/Browser/console
Run Dusk in GitHub Actions Start ChromeDriver and Laravel’s built-in server, then run php artisan dusk:
name : Dusk tests on : [ push , pull_request ] jobs : dusk : runs-on : ubuntu-latest env : APP_URL : http://127.0.0.1:8000 DB_USERNAME : root DB_PASSWORD : root MAIL_MAILER : log steps : - uses : actions/checkout@v5 - run : cp .env.example .env - run : composer install --no-progress --prefer-dist --optimize-autoloader - run : php artisan key:generate - run : php artisan dusk:chrome-driver --detect - run : ./vendor/laravel/dusk/bin/chromedriver-linux --port=9515 & - run : php artisan serve --no-reload & - run : php artisan dusk
Official documentation
Laravel Dusk official docs Review the full Dusk API, including waits, assertions, keyboard and mouse interactions, dialogs, and frames.
