Lib Innerbrowser Laravel Package

Technical Evaluation

Architecture Fit

• Core Use Case Alignment: Perfectly fits Laravel’s testing stack by enabling in-memory HTTP request simulation (e.g., form submissions, redirects, header assertions) without browser overhead. Aligns with Laravel’s Http testing layer (e.g., actingAs(), json(), assertStatus()) but extends it with DOM inspection—critical for UI-centric validation (e.g., flash messages, form errors) in acceptance tests.
• Modular Design: Acts as a dependency for Codeception’s PhpBrowser/Symfony modules, meaning integration is opinionated but seamless for Laravel projects already using Codeception. For non-Codeception Laravel projects, requires wrapping (e.g., via a custom TestCase trait).
• Laravel-Specific Synergies:
  • Middleware/Controller Testing: Simulates authenticated requests (e.g., $I->amOnPage('/dashboard') with session cookies) without spinning up a full browser.
  • View Layer Validation: Asserts rendered Blade templates (e.g., $I->see('Welcome')) or CSRF tokens in forms.
  • Database-Driven Workflows: Tests that combine HTTP requests with Eloquent operations (e.g., Post::create() followed by $I->seeInDatabase()).

Integration Feasibility

• Laravel Compatibility: Explicitly supports Symfony 7/8 (via symfony/dom-crawler) and PHPUnit 10–13, aligning with Laravel’s latest LTS (v10+). No direct Laravel dependencies, but works harmoniously with:
  • laravel/framework (for request/response handling).
  • codeception/codeception (for test suites).
  • codeception/module-laravel (for Laravel-specific helpers like seeInDatabase()).
• Dependency Conflicts: Low risk. Only conflicts arise if mixing Symfony 4/5 (deprecated in newer releases) or PHPUnit <10. Laravel’s default stack (Symfony 6+, PHPUnit 10) is fully supported.
• Testing Scope:
  • Supported: Unit/integration tests for controllers, middleware, Blade rendering, and form submissions.
  • Unsupported: JavaScript-heavy workflows (use Laravel Dusk/Playwright), real-time WebSocket interactions, or SPAs.

Technical Risk

Key Questions for the TPM

1. Testing Strategy:
   • Are we prioritizing speed (use Http::fake() for API tests) or UI fidelity (InnerBrowser for Blade/form validation)?
   • Should InnerBrowser replace Laravel’s built-in TestResponse assertions, or supplement them for DOM-specific checks?
2. Toolchain Alignment:
   • Does the team already use Codeception? If not, what’s the cost to adopt it (e.g., suite config, helper methods)?
   • Are there legacy tests using Selenium/Dusk that could migrate to InnerBrowser for faster execution?
3. Laravel-Specific Needs:
   • Do tests require authentication (e.g., Sanctum/Passport)? InnerBrowser handles sessions via $I->amLoggedInAs().
   • Are there custom Blade directives or JavaScript-rendered content that InnerBrowser can’t parse?
4. CI/CD Impact:
   • How does InnerBrowser’s execution time compare to current tests? (Aim for <1s per test for CI viability.)
   • Can we parallelize Codeception tests (requires codeception/parallel module)?

Integration Approach

Stack Fit

• Primary Integration Points:
  • Codeception + Laravel Module: The gold standard. InnerBrowser powers PhpBrowser/Symfony modules, which integrate with codeception/module-laravel via:

    // tests/acceptance.suite.yml
    modules:
      enabled:
        - Laravel:
            environment_file: .env.testing
        - PhpBrowser: ~  # Uses InnerBrowser under the hood
    

  • Standalone Laravel: For projects not using Codeception, wrap InnerBrowser in a custom TestCase trait:

    use Codeception\Lib\InnerBrowser;
    
    trait InnerBrowserTestTrait {
        protected InnerBrowser $browser;
    
        protected function setUp(): void {
            $this->browser = new InnerBrowser();
            $this->browser->setRequestFactory($this->app->make('http.client'));
        }
    
        protected function submitForm(string $url, array $data): void {
            $this->browser->amOnPage($url);
            $this->browser->fillField('#email', $data['email']);
            $this->browser->submitForm('#login-form');
        }
    }
    

• Alternatives:
  • Laravel Dusk: For JavaScript-heavy tests (but slower; ~5–10x execution time).
  • PestPHP + mocks: For unit tests (no DOM inspection).
  • Symfony Panther: If avoiding Codeception entirely (similar API to InnerBrowser).

Migration Path

1. Assessment Phase:
   • Audit existing tests: Identify DOM-dependent assertions (e.g., seeElement(), dontSee()) vs. API-only tests (migrate to Http::fake()).
   • Benchmark: Compare execution time of 10 representative tests with/without InnerBrowser.
2. Pilot Integration:
   • Add Codeception to composer.json:

     composer require --dev codeception/codeception codeception/module-laravel codeception/lib-innerbrowser
     

   • Configure acceptance.suite.yml with Laravel + PhpBrowser modules.
   • Rewrite 1–2 critical test suites (e.g., user authentication flow) using InnerBrowser.
3. Full Adoption:
   • Replace Selenium/Dusk tests with InnerBrowser for non-JS workflows.
   • Deprecate custom DOM parsers (e.g., simple_html_dom) in favor of InnerBrowser’s Crawler.
   • Phase out: Legacy TestResponse assertions that duplicate InnerBrowser’s DOM checks.

Compatibility

Sequencing

1. Phase 1: Setup (1–2 days)
   • Install Codeception + modules.
   • Configure acceptance.suite.yml and PhpBrowser.
   • Write 2–3 "hello world" tests (e.g., assert homepage title, submit a contact form).
2. Phase 2: Migration (1–2 weeks)
   • Convert high-value, DOM-dependent tests (e.g., checkout flow, error pages).
   • Replace TestResponse::assertSee() with $I->see() where DOM inspection is needed.
3. Phase 3: Optimization (Ongoing)
   • Cache DOM snapshots for slow tests (e.g., dom_dump() in `