Testbench Browser Kit Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require --dev orchestra/testbench-browser-kit
   

2. Extend Base TestCase: Replace Orchestra\Testbench\TestCase with Orchestra\Testbench\BrowserKit\TestCase in your test base class:

   use Orchestra\Testbench\BrowserKit\TestCase as BaseTestCase;
   
   abstract class TestCase extends BaseTestCase
   {
       public $baseUrl = 'http://localhost';
   }
   

3. First Test: Write a simple test to verify a route or form interaction:

   public function testBasicRoute()
   {
       $this->visit('/')
            ->see('Expected Text');
   }
   

Where to Look First

• README.md: Focus on the "Usages" section for quick examples.
• Testbench Documentation: Understand how BrowserKit integrates with Laravel’s testing helpers.
• Laravel BrowserKit Testing: Reference laravel/browser-kit-testing for advanced usage.

Implementation Patterns

Core Workflows

1. Route Testing: Use visit() and visitRoute() for GET requests:

   $this->visit('/dashboard')
        ->seeRouteIs('dashboard');
   

   $this->visitRoute('profile.edit', ['user' => 1]);
   

2. Form Interaction: Chain methods for form submission:

   $this->visit('/register')
        ->type('John Doe', 'name')
        ->check('terms')
        ->press('Submit')
        ->seePageIs('/welcome');
   

3. API Testing: Use json() for API endpoints:

   $this->json('POST', '/api/users', ['name' => 'Test'])
        ->seeJsonEquals(['success' => true]);
   

4. Authentication: Authenticate users with actingAs():

   $user = create('App\Models\User');
   $this->actingAs($user)
        ->visit('/profile')
        ->see('Welcome, ' . $user->name);
   

5. Middleware Isolation: Disable middleware for specific tests:

   $this->withoutMiddleware()
        ->visit('/admin')
        ->assertResponseOk();
   

Integration Tips

• Package Testing: Use TestCase to test package routes, middleware, and views in isolation.
• Testbench Setup: Leverage getPackageProviders() and getPackageAliases() to mock dependencies.
• Custom Assertions: Combine with Laravel’s assert* methods (e.g., assertViewHas()) for granular checks.

Gotchas and Tips

Pitfalls

1. Base URL Mismatch: Ensure $baseUrl in TestCase matches your test environment (e.g., http://localhost). Fix: Override $baseUrl in child test classes or use TestCase::setBaseUrl().

2. Session Persistence: withSession() data is not automatically persisted across tests. Fix: Use actingAs() for authenticated sessions or manually set session data per test.

3. Middleware Conflicts: Disabling middleware globally (WithoutMiddleware) may hide critical issues. Fix: Use withoutMiddleware() sparingly and test middleware logic separately.

4. CSRF Token Errors: Forms may fail if CSRF protection is enabled but tokens aren’t included. Fix: Use press() or manually add CSRF tokens in attach() for file uploads.

5. Dynamic Routes: visitRoute() requires named routes to exist in the test environment. Fix: Define routes in routes/web.php or use Route::get() in TestCase::setUp().

Debugging Tips

• Inspect Responses: Use dump($this->response->getContent()) to debug HTML/API responses.
• Log Requests: Enable Laravel’s debug mode (APP_DEBUG=true) to log HTTP requests.
• Testbench Isolation: Reset the test environment between tests:

  public function tearDown(): void
  {
      Artisan::call('migrate:reset');
      parent::tearDown();
  }
  

Extension Points

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

   class PackageTestCase extends TestCase
   {
       protected function assertPackageConfig()
       {
           $this->assertConfig('package.key', 'expected_value');
       }
   }
   

2. Mocking Dependencies: Use Testbench’s getApplication() to mock services:

   $this->app->instance('App\Contracts\Service', MockService::class);
   

3. Custom Middleware: Override getMiddleware() to inject test-specific middleware:

   protected function getMiddleware()
   {
       return [
           \App\Http\Middleware\TestMiddleware::class,
       ];
   }
   

4. BrowserKit Extensions: Add custom assertions to TestCase:

   protected function seePackageView($viewName)
   {
       $this->see($viewName);
       $this->assertViewIs($viewName);
   }