Testbench Dusk Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies Add to your package's composer.json:

   "require-dev": {
       "orchestra/testbench-dusk": "^11.0",
       "laravel/dusk": "^8.3.5",
       "phpunit/phpunit": "^12.0"
   }
   

   Run composer update.

2. Configure Dusk Publish the Dusk config:

   php artisan vendor:publish --provider="Laravel\Dusk\DuskServiceProvider" --tag=dusk-config
   

   Update dusk.config.php to include:

   'browser' => [
       'disable_search_engine_choice_screen' => true,
       'disable_smooth_scrolling' => true,
   ],
   

3. First Test Create a test class extending Orchestra\TestbenchDusk\TestCase:

   use Orchestra\TestbenchDusk\TestCase;
   
   class ExampleTest extends TestCase {
       public function test_package_feature() {
           $this->browse(function ($browser) {
               $browser->visit('/')
                       ->assertSee('Expected Package Content');
           });
       }
   }
   

   Run with:

   php artisan dusk
   

Key First Use Case

Testing Package UI Components Use Dusk to verify your package’s frontend interactions (e.g., modals, forms, or livewire components) in isolation. Example:

public function test_package_modal() {
    $this->browse(function ($browser) {
        $browser->visit('/admin/dashboard')
                ->click('@open-modal-button')
                ->waitForText('Modal Title')
                ->assertSee('Package-Specific Content');
    });
}

Implementation Patterns

Core Workflows

1. Testbench + Dusk Integration Leverage Testbench’s getPackageProviders() and getEnvironmentSetUp() alongside Dusk:

   protected function getEnvironmentSetUp($app) {
       // Testbench setup
       $app->make(Kernel::class)->bootstrap();
   
       // Dusk-specific tweaks
       $app['config']->set('app.debug', true);
   }
   

2. Package-Specific Context Override getPackageAliases() to ensure your package’s Blade directives/aliases are available:

   protected function getPackageAliases($app) {
       return [
           'package-alias' => 'Package\\ServiceProvider',
       ];
   }
   

3. CI Optimization Use beforeServingApplication() to preload assets or mock APIs:

   protected function beforeServingApplication($server) {
       $server->addMiddleware(function ($request, $next) {
           if ($request->is('api/*')) {
               return response()->json(['data' => 'mocked']);
           }
           return $next($request);
       });
   }
   

4. Livewire/Alpine Testing Combine with dusk-livewire helpers:

   $browser->wire('livewire-component')
           ->assertSee('Livewire Content')
           ->call('actionMethod');
   

Common Patterns

• Data Factories: Use Testbench’s factories to seed test data:

  $this->loadMigrationsFrom(__DIR__.'/../../database/migrations');
  factory(\App\Models\User::class)->create();
  

• Artisan Commands: Test package commands via Dusk:

  $this->artisan('package:command')
       ->assertExitCode(0)
       ->assertOutputContains('Success');
  

• Browser Actions: Chain Dusk actions for complex flows:

  $browser->visit('/')
          ->type('email', 'test@example.com')
          ->press('Submit')
          ->waitFor('.success-message');
  

Gotchas and Tips

Pitfalls

1. Headless Mode Conflicts

   • Issue: Dusk’s headless Chrome may fail with --disable-search-engine-choice-screen in CI.
   • Fix: Explicitly set in dusk.config.php:

     'browser' => [
         'headless' => true,
         'args' => [
             '--disable-gpu',
             '--no-sandbox',
             '--disable-dev-shm-usage',
         ],
     ],
     

2. Asset Compilation

   • Issue: Missing compiled assets (e.g., mix-manifest.json) cause 404s.
   • Fix: Run npm run dev in CI or use beforeServingApplication():

     $this->artisan('vendor:publish', ['--tag' => 'public']);
     

3. Session Persistence

   • Issue: Dusk sessions reset between tests.
   • Fix: Use persistentSession() in TestCase:

     protected $persistentSession = true;
     

4. Livewire Debugging

   • Issue: Livewire components fail silently.
   • Fix: Enable Livewire’s debug mode:

     $this->app->make(\Livewire\Livewire::class)->debug();
     

Debugging Tips

• Browser Logs: Access via:

  $browser->driver->manage()->logs()->get('browser');
  

• Screenshots: Auto-capture failures with:

  $this->expectException(\Facebook\WebDriver\Exception\NoSuchElementException::class);
  

• Slow Tests: Add waits explicitly:

  $browser->waitFor(5)->toBeVisible('#element');
  

Extension Points

1. Custom Dusk Helpers Extend TestCase to add package-specific methods:

   protected function assertPackageFeature($browser, $feature) {
       $browser->assertSee('Package Feature: ' . $feature);
   }
   

2. Mocking HTTP Requests Use Http::fake() in beforeApplication():

   protected function beforeApplication() {
       Http::fake([
           'api.example.com/*' => Http::response('Mocked'),
       ]);
   }
   

3. Parallel Testing Configure in phpunit.xml:

   <phpunit>
       <extensions>
           <extension class="Dusk\Extensions\ParallelExtension"/>
       </extensions>
   </phpunit>
   

Pro Tips

• Test Isolation: Use refreshDatabase() for each test:

  public function setUp(): void {
      parent::setUp();
      $this->refreshDatabase();
  }
  

• Cross-Browser Testing: Add Firefox support:

  $this->browse(function ($browser) {
      $browser->driver->manage()->window()->setSize(1920, 1080);
  });
  

• Performance: Cache Dusk assets in CI:

  php artisan dusk:cache