Dusk Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require --dev laravel/dusk
   

   Laravel Dusk includes a DuskTestCase base class and a Browser class for testing.

2. Configuration: Run the Dusk installer:

   php artisan dusk:install
   

   This sets up the necessary ChromeDriver and configures the DuskTestCase.

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

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

4. Run Tests:

   php artisan dusk
   

Implementation Patterns

Common Workflows

Authentication Testing

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

Form Interactions

public function it_submits_a_form()
{
    $this->browse(function (Browser $browser) {
        $browser->visit('/contact')
                ->type('name', 'John Doe')
                ->select('country', 'United States')
                ->press('Submit')
                ->assertSee('Thank you!');
    });
}

Dynamic Content Assertions

public function it_asserts_dynamic_content()
{
    $this->browse(function (Browser $browser) {
        $browser->visit('/posts')
                ->waitForText('Post Title')
                ->assertSee('Post Title')
                ->assertSeeIn('@posts', 'Published');
    });
}

Vue.js Testing

public function it_asserts_vue_data()
{
    $this->browse(function (Browser $browser) {
        $browser->visit('/dashboard')
                ->assertVue('count', 5)
                ->assertVueIsNot('error', null);
    });
}

Responsive Testing

public function it_takes_responsive_screenshots()
{
    $this->browse(function (Browser $browser) {
        $browser->visit('/dashboard')
                ->resize(1920, 1080)
                ->screenshot('desktop')
                ->resize(375, 812)
                ->screenshot('mobile');
    });
}

Integration Tips

• Middleware: Use withSession() to test authenticated routes:

  $this->browse(function (Browser $browser) {
      $browser->withSession(function ($browser) {
          $browser->loginAs($user)
                  ->visit('/admin')
                  ->assertSee('Admin Panel');
      });
  });
  

• Custom Commands: Extend Browser for reusable actions:

  use Laravel\Dusk\Browser;
  
  class CustomBrowser extends Browser
  {
      public function fillProfile($name, $email)
      {
          $this->type('name', $name)
               ->type('email', $email);
      }
  }
  

• Headless Mode: Run tests without opening a browser:

  php artisan dusk --headless
  

Gotchas and Tips

Pitfalls

1. Slow Tests:

   • Avoid sleep(); use waitFor() methods like waitForText() or waitForLocation().
   • Example:

     $browser->waitForText('Loading...')->assertDontSee('Loading...');
     

2. Flaky Selectors:

   • Prefer stable selectors (e.g., IDs, data attributes) over dynamic ones like //div[2].
   • Use elseWhenAvailable() for fallback selectors:

     $browser->click('@submit-button')->elseWhenAvailable('@fallback-submit');
     

3. ChromeDriver Issues:

   • Ensure ChromeDriver matches your Chrome version. Dusk auto-downloads it, but manual updates may be needed.
   • Debug with:

     php artisan dusk:chrome-driver
     

4. Vue.js Quirks:

   • For Vue 2 vs. Vue 3, use assertVue() with the correct syntax:

     // Vue 2 (Options API)
     $browser->assertVue('count', 5);
     
     // Vue 3 (Composition API)
     $browser->assertVue('count.value', 5);
     

5. Assertion Failures:

   • Use ->screenshot() before assertions to debug:

     $browser->assertSee('Error')->screenshot('error-state');
     

   • Enable source capture on failure in phpunit.xml:

     <env name="DUSK_CAPTURE_SOURCE" value="true"/>
     

Debugging Tips

• Log Browser Actions: Enable debug mode in DuskTestCase:

  protected $debug = true;
  

• Inspect Elements: Use pause() to manually inspect the page:

  $browser->pause(5); // Pauses for 5 seconds
  

• Custom Error Handling: Override failed() in DuskTestCase:

  protected function failed(TestResult $result)
  {
      $this->browse(function (Browser $browser) {
          $browser->screenshot('failure-' . $result->test->getName());
      });
  }
  

Extension Points

1. Custom Assertions: Extend Browser to add assertions:

   class CustomBrowser extends Browser
   {
       public function assertTableRowExists($rowText)
       {
           $this->assertSee($rowText);
       }
   }
   

2. Hooks: Use setUp() and tearDown() in DuskTestCase:

   protected function setUp(): void
   {
       parent::setUp();
       $this->artisan('migrate:fresh');
   }
   

3. Configuration: Override Dusk settings in phpunit.xml:

   <env name="DUSK_BROWSER" value="chrome"/>
   <env name="DUSK_HEADLESS" value="true"/>
   

4. Parallel Testing: Use Pest for parallel test execution:

   composer require --dev pestphp/pest --dev pestphp/pest-plugin-laravel
   

   Update phpunit.xml to use Pest’s parallelizer.