Mastering Laravel Dusk: A Comprehensive Guide to Browser Automation and Testing

Laravel Dusk provides an expressive, easy-to-use browser automation and testing API. By default, Dusk doesn't require JDK or Selenium on your local machine, using a standalone ChromeDriver instead. Here's everything you need to know to get started with Laravel Dusk and elevate your testing game.

Installation

To begin, install Google Chrome and add the laravel/dusk Composer dependency to your project:

composer require laravel/dusk --dev

If you are manually registering Dusk's service provider, ensure it's not registered in your production environment to avoid unauthorized access.

Next, execute the dusk:install Artisan command:

php artisan dusk:install

This command creates a tests/Browser directory, an example Dusk test, and installs the Chrome Driver binary for your OS.

Set the APP_URL environment variable in your .env file to match the URL you use to access your application in a browser.

Managing ChromeDriver Installations

To install a different version of ChromeDriver:

# Latest version
php artisan dusk:chrome-driver

# Specific version
php artisan dusk:chrome-driver 86

# For all supported OSs
php artisan dusk:chrome-driver --all

# Match detected Chrome/Chromium version
php artisan dusk:chrome-driver --detect

Ensure the binaries are executable if you encounter issues:

chmod -R 0755 vendor/laravel/dusk/bin/

Using Other Browsers

Dusk uses Chrome by default, but you can use any Selenium-compatible browser. In your tests/DuskTestCase.php file, remove the startChromeDriver call:

public static function prepare(): void
{
    // static::startChromeDriver();
}

Modify the driver method to connect to your desired browser:

use Facebook\WebDriver\Remote\RemoteWebDriver;

protected function driver(): RemoteWebDriver
{
    return RemoteWebDriver::create(
        'http://localhost:4444/wd/hub', DesiredCapabilities::phantomjs()
    );
}

Getting Started

Generating Tests

Generate a Dusk test with:

php artisan dusk:make RegisterTest

Resetting the Database After Each Test

Dusk tests interact with database-driven pages, but avoid using the RefreshDatabase trait. Instead, use DatabaseMigrations or DatabaseTruncation.

Using Database Migrations:

use Illuminate\Foundation\Testing\DatabaseMigrations;
use Laravel\Dusk\Browser;

uses(DatabaseMigrations::class);

Using Database Truncation:

use Illuminate\Foundation\Testing\DatabaseTruncation;
use Laravel\Dusk\Browser;

uses(DatabaseTruncation::class);

protected $tablesToTruncate = ['users'];
protected $exceptTables = ['users'];
protected $connectionsToTruncate = ['mysql'];

protected function beforeTruncatingDatabase(): void { }
protected function afterTruncatingDatabase(): void { }

Running Tests

Run your browser tests with:

php artisan dusk

Re-run failing tests with:

php artisan dusk:fails

Run tests for a specific group:

php artisan dusk --group=foo

For Laravel Sail users, refer to the Sail documentation for configuring and running Dusk tests.

Conclusion

Laravel Dusk simplifies browser testing, ensuring your applications perform as expected across different scenarios. By following this guide, you'll be equipped to harness the full potential of Laravel Dusk, creating robust, reliable, and automated browser tests for your applications. Happy testing!