Dusk Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev laravel/dusk
   

   Run the Dusk installer:

   php artisan dusk:install
   

   This installs Chromedriver, configures PHPUnit, and sets up the base test class.

2. First Test: Create a test in tests/Browser/ExampleTest.php:

   <?php
   namespace Tests\Browser;
   
   use Laravel\Dusk\TestCase;
   
   class ExampleTest extends TestCase
   {
       /** @test */
       public function it_loads_the_homepage()
       {
           $this->visit('/')
                ->assertSee('Welcome');
       }
   }
   

   Run the test:

   php artisan dusk
   

3. Key Files:

   • tests/Browser/ – Default directory for Dusk tests.
   • phpunit.xml – Configured for Dusk (includes Selenium setup).
   • DuskTestCase.php – Base test class (auto-generated by installer).

Implementation Patterns

Core Workflows

1. Basic Interaction:

   $this->visit('/dashboard')
        ->type('email', 'user@example.com')
        ->press('Login')
        ->assertPathIs('/dashboard');
   

2. Form Testing:

   $this->visit('/register')
        ->type('name', 'John Doe')
        ->select('country', 'United States')
        ->check('terms')
        ->press('Register')
        ->assertSee('Account created!');
   

3. Dynamic Assertions:

   $this->visit('/posts')
        ->assertSeeIn('h1', 'Latest Posts')
        ->assertPathContains('/posts')
        ->assertAttributeMissing('input[name="hidden"]', 'value');
   

4. Component Testing:

   $this->component('Alert', ['message' => 'Success!'])
        ->assertSee('Success!');
   

5. Page Objects: Define reusable page interactions in tests/Browser/Pages/:

   // tests/Browser/Pages/DashboardPage.php
   namespace Tests\Browser\Pages;
   
   use Laravel\Dusk\Page;
   
   class DashboardPage extends Page
   {
       public function assertSeeUser($name)
       {
           return $this->assertSee($name);
       }
   }
   

   Use in tests:

   $this->visit('/dashboard')
        ->assertSeeUser('John Doe');
   

6. Screenshots & Debugging:

   $this->visit('/error-page')
        ->screenshot('error-page')
        ->dump(); // Dumps browser state
   

Integration Tips

• Laravel Features: Use actingAs() for auth:

  $this->actingAs(User::first())
       ->visit('/profile');
  

• API + UI: Combine with HTTP tests:

  $response = $this->post('/login', ['email' => 'test@example.com']);
  $this->visit('/dashboard')->assertSee('Welcome');
  

• Headless Mode: Run in CI:

  php artisan dusk --headless
  

• Custom Drivers: Override DUSK_DRIVER_URL in .env:

  DUSK_DRIVER_URL=remote:http://selenium-standalone-chrome:4444/wd/hub
  

Gotchas and Tips

Common Pitfalls

1. Element Selection:

   • Prefer exact matches over partial text (e.g., ->click('#submit-button') over ->click('button', 'Submit')).
   • Use ->waitFor() for dynamic content:

     $this->waitFor(5)->assertSee('Loaded');
     

2. Flaky Tests:

   • Add delays for slow networks:

     $this->pause(2000); // 2-second pause
     

   • Use ->clickOnce() (or ->clickWhen()) to avoid double-clicks:

     $this->clickOnce('#submit')->assertPathIs('/success');
     

3. Configuration Quirks:

   • Chromedriver Path: If tests fail silently, ensure Chromedriver is in vendor/laravel/dusk/bin/chromedriver.
   • Port Conflicts: Explicitly set DUSK_DRIVER_PORT=9515 if using custom drivers.
   • Headless Issues: Use --headless=new (Chrome 112+) or --headless=old for compatibility.

4. Debugging:

   • Screenshots: Enable auto-screenshots on failure in phpunit.xml:

     <env name="DUSK_SCREENSHOTS" value="1"/>
     

   • Logs: Check storage/logs/dusk-*.log for Selenium errors.
   • Console Output: Use ->dump() or ->dd() to inspect the browser state.

5. Performance:

   • Parallel Tests: Use --parallel in PHPUnit for faster runs:

     php artisan dusk --parallel
     

   • Skip Heavy Tests: Tag tests with @slow and filter them out in CI:

     php artisan dusk --exclude-group=slow
     

Extension Points

1. Custom Assertions: Extend Laravel\Dusk\Browser in a trait:

   trait CustomAssertions
   {
       public function assertElementIsVisible($selector)
       {
           return $this->assertTrue($this->element($selector)->isVisible());
       }
   }
   

   Use in tests:

   $this->assertElementIsVisible('#modal');
   

2. Custom Selectors: Override find() in a subclass:

   class CustomBrowser extends Browser
   {
       public function findCustomSelector($selector)
       {
           return $this->driver->findElement(WebDriverBy::css($selector));
       }
   }
   

3. Pest Integration: Use uses(DuskTestCase::class) in Pest tests:

   it('loads the homepage', function () {
       $this->visit('/')->assertSee('Welcome');
   })->uses(DuskTestCase::class);
   

4. CI Optimization:

   • Cache Chromedriver between runs:

     docker run --rm -d -p 9515:9515 selenium/standalone-chrome
     

   • Use DUSK_DRIVER=remote in .env to connect to a shared Selenium grid.

5. Vue/React Testing: Use assertVue() for SPAs:

   $this->assertVue('data().message', 'Welcome');
   

   Or assertJavascript() for custom JS checks:

   $this->assertJavascript('document.title === "Home"');