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 Use Case: Write a simple test to verify a route response:

   public function testHomepageLoads()
   {
       $this->visit('/')
            ->see('Welcome');
   }
   

Where to Look First

• README.md: Focus on the "Usages" section for quick API reference.
• Testbench Documentation: Understand Laravel’s built-in testing features (e.g., DatabaseTransactions, WithoutMiddleware).
• BrowserKit Testing Docs: laravel/browser-kit-testing for advanced assertions.

Implementation Patterns

Core Workflows

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

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

2. Form Interaction: Chain methods for form submission:

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

3. API Testing: Use json() for HTTP verbs:

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

4. Authentication: Authenticate users with actingAs():

   $user = create('App\Models\User');
   $this->actingAs($user)->visit('/dashboard');
   

5. Middleware Isolation: Disable middleware for specific tests:

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

Integration Tips

• Package Testing: Use Testbench to load your package in isolation:

  protected function getPackageProviders($app)
  {
      return ['YourPackage\\ServiceProvider'];
  }
  

• Custom Assertions: Extend TestCase for reusable assertions:

  protected function assertPackageFeatureExists()
  {
      $this->visit('/package-feature')->see('Expected Text');
  }
  

• Session Sharing: Preload session data:

  $this->withSession(['preloaded' => 'data'])->visit('/');
  

Gotchas and Tips

Pitfalls

1. Base URL Mismatch:

   • Issue: Tests fail due to incorrect $baseUrl (e.g., http://localhost vs. https://example.test).
   • Fix: Set $baseUrl in your TestCase or override it per test:

     $this->baseUrl = 'https://example.test';
     

2. Middleware Leaks:

   • Issue: Forgetting withoutMiddleware() can cause tests to fail if middleware (e.g., auth) isn’t mocked.
   • Fix: Use WithoutMiddleware trait or withoutMiddleware() in tests.

3. Session Persistence:

   • Issue: Session data not persisting across chained requests.
   • Fix: Use withSession() before the first request in a chain.

4. Route Caching:

   • Issue: Route changes not reflected in tests due to cached routes.
   • Fix: Clear routes in setUp():

     public function setUp(): void
     {
         parent::setUp();
         $this->app['router']->refreshRoutes();
     }
     

Debugging Tips

• Inspect Responses: Use dump() or dd() on the response object:

  $response = $this->call('GET', '/');
  dd($response->getContent());
  

• Log Requests: Enable Laravel’s debug mode and check logs for failed requests:

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

• Testbench Isolation: Ensure getPackageProviders() and getEnvironmentSetUp() are correctly defined to avoid conflicts with the host app.

Extension Points

1. Custom Assertions: Extend TestCase to add domain-specific assertions:

   public function assertPackageConfigLoaded()
   {
       $this->assertEquals('expected', config('package.key'));
   }
   

2. Hooks for Setup/Teardown: Override setUp()/tearDown() for shared test logic:

   protected function setUp(): void
   {
       parent::setUp();
       $this->artisan('package:publish-config');
   }
   

3. Mocking Dependencies: Use Laravel’s mocking tools (e.g., Mockery) within tests:

   $mock = Mockery::mock('alias:YourPackage');
   $this->app->instance('YourPackage', $mock);
   

4. Parallel Testing: Leverage PHPUnit’s --parallel flag for faster test suites, but ensure tests are stateless (e.g., avoid shared DB state).