Browser Laravel Package

Technical Evaluation

Architecture Fit

• Symfony-Centric: The package is optimized for Symfony (KernelBrowser) and Symfony Panther (PantherBrowser), making it a near-perfect fit for Laravel applications only if:
  • Using Symfony components (e.g., HttpKernel, BrowserKit, DomCrawler).
  • Requiring fluent, expressive test assertions beyond Laravel’s built-in HttpTestCase.
  • Needing JavaScript testing (PantherBrowser).
• Laravel Compatibility:
  • KernelBrowser can integrate via Symfony’s HttpKernel (Laravel’s core uses this).
  • PantherBrowser requires Symfony Panther, which is not natively supported in Laravel (would need manual setup).
  • No native Laravel test case integration (would require wrapping or extending Laravel’s TestCase).

Integration Feasibility

• High for KernelBrowser:
  • Laravel’s HttpTestCase already uses BrowserKit/DomCrawler under the hood.
  • Can replace or extend Laravel’s test assertions with zenstruck/browser.
  • Example: Replace assertSee() with assertSeeIn('h1', 'Title') for more granular control.
• Medium for PantherBrowser:
  • Requires Symfony Panther (symfony/panther), which is not in Laravel’s default stack.
  • Would need additional setup (e.g., Docker/Selenium for headless browsers).
  • Overhead: Slower tests due to real browser interactions.
• Dependency Risk:
  • Adds Symfony-specific dependencies (BrowserKit, DomCrawler, Panther).
  • Potential version conflicts if Laravel/Symfony components diverge.

Technical Risk

Key Questions

1. Why not use Laravel’s native HttpTestCase or Dusk (for JS)?
   • If the goal is simpler assertions, zenstruck/browser provides a more fluent API than Laravel’s.
   • If JavaScript testing is needed, Dusk (Laravel’s official JS testing) may be a better fit.
2. Will this break existing tests?
   • KernelBrowser assertions may differ from Laravel’s (e.g., assertSee() vs. assertSeeIn()).
   • Recommendation: Start with a subset of tests and migrate incrementally.
3. How will this interact with Laravel’s test helpers?
   • Conflict risk: If using both HttpTestCase and HasBrowser, ensure consistent setup/teardown.
   • Solution: Extend Laravel’s TestCase to include HasBrowser.
4. Is PantherBrowser worth the complexity?
   • Only if JavaScript-heavy features (e.g., SPAs, complex interactions) are being tested.
   • Otherwise, stick to KernelBrowser or Laravel Dusk.
5. How will CI/CD be impacted?
   • PantherBrowser requires Selenium/Docker, increasing build times and infrastructure costs.
   • KernelBrowser adds minimal overhead.

Integration Approach

Stack Fit

Migration Path

1. Phase 1: KernelBrowser Adoption (Low Risk)

   • Step 1: Add zenstruck/browser to tests/ composer.json.
   • Step 2: Extend Laravel’s TestCase to include HasBrowser:

     use Zenstruck\Browser\Test\HasBrowser;
     
     abstract class TestCase extends \Illuminate\Foundation\Testing\TestCase
     {
         use HasBrowser;
     }
     

   • Step 3: Replace select tests with zenstruck/browser assertions (e.g., assertSeeIn instead of assertSee).
   • Step 4: Leverage KernelBrowser-specific features (e.g., actingAs, expectException, assertJsonMatches).

2. Phase 2: PantherBrowser (High Risk, Optional)

   • Step 1: Install symfony/panther and selenium-server.
   • Step 2: Extend TestCase to support PantherBrowser:

     use Zenstruck\Browser\Test\PantherBrowser;
     
     abstract class TestCase extends \Illuminate\Foundation\Testing\TestCase
     {
         protected function createPantherBrowser(): PantherBrowser
         {
             return new PantherBrowser();
         }
     }
     

   • Step 3: Use only for JS-critical tests; keep KernelBrowser for API/non-JS tests.

3. Phase 3: Debugging & Artifacts

   • Configure BrowserExtension in phpunit.xml:

     <extensions>
         <bootstrap class="Zenstruck\Browser\Test\BrowserExtension" />
     </extensions>
     

   • Benefit: Automatic screenshots/source saves on test failures.

Compatibility

Sequencing

1. Start with KernelBrowser for API and non-JS tests (highest ROI).
2. Replace Laravel assertions incrementally (e.g., 1 test file at a time).
3. Adopt PantherBrowser only if JS testing is a blocker (last resort due to complexity).
4. Enable BrowserExtension for debugging after core tests are migrated.
5. Benchmark performance to ensure no regression in test suite speed.

Operational Impact

Maintenance

Support

• Pros:
  • Fluent API reduces boilerplate (e.g., assertSeeIn('h1', 'Title') vs. multiple assertSee calls).
  • Automatic debugging artifacts (BrowserExtension) speeds up issue resolution.
  • Active maintenance (last release: 2026-05-28).
• Cons:
  • Symfony-centric docs may require Laravel-specific adjustments.
  • No official Laravel support (community-driven).
  • PantherBrowser requires additional infrastructure (Selenium).

Scaling

|