Testbench Dusk Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies:

   composer require --dev orchestra/testbench-dusk
   composer require --dev laravel/dusk
   

2. Configure Dusk: Add DuskTestCase to your test class and extend Orchestra\Testbench\DuskTestCase:

   use Orchestra\Testbench\DuskTestCase;
   
   class ExampleDuskTest extends DuskTestCase
   {
       // Test methods here
   }
   

3. First Use Case: Test a package's frontend functionality (e.g., a dashboard widget):

   public function test_package_dashboard_widget()
   {
       $this->browse(function (Browser $browser) {
           $browser->visit('/dashboard')
                   ->assertSee('Package Widget Title');
       });
   }
   

4. Key Files:

   • tests/DuskTestCase.php (base class)
   • tests/BrowserTests/ (Dusk test directory)
   • phpunit.xml (ensure Dusk is enabled)

Implementation Patterns

Core Workflows

1. Package Integration Testing:

   • Use beforeServingApplication() to mock package dependencies:

     protected function beforeServingApplication()
     {
         $this->app->singleton('package.service', fn() => MockService::class);
     }
     

2. Browser Automation:

   • Chain Dusk actions with assertions:

     $browser->visit('/admin')
             ->click('@submit-button')
             ->assertPathIs('/confirmation')
             ->assertSee('Success!');
     

3. Test Isolation:

   • Reset state between tests using beforeApplicationCreated():

     protected function beforeApplicationCreated()
     {
         $this->app->make('db')->connection()->getSchemaBuilder()->dropAllTables();
     }
     

4. Custom Commands:

   • Extend Dusk with package-specific commands:

     $browser->visit('/')
             ->packageCommand('triggerEvent', ['param1', 'param2'])
             ->assertDumped('Expected output');
     

Integration Tips

• Testbench + Dusk Synergy: Combine createApplication() with Dusk’s browser automation:

  $this->app = $this->createApplication();
  $this->app->register(\Your\Package\ServiceProvider::class);
  

• Headless Mode: Run Dusk tests headless in CI:

  php artisan dusk --headless --chrome-args="--no-sandbox"
  

• Parallel Testing: Use phpunit --group=dusk with parallel workers:

  <!-- phpunit.xml -->
  <phpunit>
      <groups>
          <group name="dusk">Dusk tests</group>
      </groups>
  </phpunit>
  

Gotchas and Tips

Pitfalls

1. ChromeDriver Path:

   • Ensure CHROME_DRIVER environment variable points to the correct binary:

     export CHROME_DRIVER=/usr/local/bin/chromedriver
     

   • Debug: Use --debug flag to see Dusk’s ChromeDriver resolution.

2. Package Registration:

   • Forgetting to register the package in beforeServingApplication():

     // ❌ Missing registration
     protected function beforeServingApplication() {}
     
     // ✅ Correct
     protected function beforeServingApplication()
     {
         $this->app->register(\Your\Package\ServiceProvider::class);
     }
     

3. State Persistence:

   • Dusk tests run in a fresh browser instance per test. Avoid relying on global state:

     // ❌ Anti-pattern: Assumes state persists
     $browser->visit('/')->click('@button');
     
     // ✅ Pattern: Reset state explicitly
     $this->app['cache']->forget('key');
     

4. Deprecated Methods:

   • Avoid tweakApplication() (use beforeServingApplication() instead):

     // ❌ Deprecated
     $this->tweakApplication(function ($app) {});
     
     // ✅ Modern
     protected function beforeServingApplication() {}
     

Debugging

• Slow Tests:

  • Use --chrome-args="--headless --disable-gpu" to speed up CI runs.
  • Cache browser instances with DuskTestCase::useBrowserCache().

• Element Not Found:

  • Verify selectors with @ prefix (e.g., @submit-button):

    $browser->click('@submit-button')->assertSee('Error'); // Debug missing element
    

• ChromeDriver Errors:

  • Check compatibility with Dusk’s requirements.
  • Fix: Update laravel/dusk and chromedriver versions.

Extension Points

1. Custom Assertions:

   $browser->assertPackageFeature('widget_visible', fn() => $browser->assertSee('Widget'));
   

2. Hooks:

   • Override beforeApplicationCreated()/afterApplicationCreated() for setup/teardown:

     protected function beforeApplicationCreated()
     {
         $this->loadMigrationsFrom(__DIR__.'/../database/migrations');
     }
     

3. Environment Config:

   • Use .env.testing for Dusk-specific settings:

     BROWSER_DRIVER=chrome
     CHROME_DRIVER=/path/to/chromedriver
     

4. Visual Regression:

   • Integrate with Applitools or Percy via custom Dusk commands.