Browser Kit Laravel Package

Product Decisions This Supports

What it actually buys us. BrowserKit is a browser simulation abstraction — request, click a link, fill and submit a form by field name, follow redirects, carry cookies, walk back and forward through history. It is not a test runner, not an HTTP client, and not, on its own, a way to test a Laravel app. It supports these product decisions:

• Regression safety for multi-step user journeys. Checkout, signup, onboarding, and settings flows are where revenue and activation live, and where refactors break things silently. BrowserKit lets us assert a sequence of user actions rather than isolated endpoint responses — the closest thing to a real user path we can run in CI without a browser binary.
• Build vs. buy on test infrastructure. The honest framing: we buy the abstraction (MIT, zero infra: no Selenium grid, no Node, no daemon) and we build the one piece that makes it work against Laravel — a concrete browser class mapping a BrowserKit request onto Illuminate\Http\Request and calling the HTTP kernel. Symfony keeps that class (KernelBrowser) in framework-bundle, not here. Budget 200–400 LOC plus its own tests, not a composer require.
• What comes free once that glue exists: form submission including hidden inputs (so CSRF tokens work when present in the rendered form), link/button selection, redirect following with limits, a spec-shaped cookie jar with domain/path/expiry handling, and history assertions — isFirstPage()/isLastPage() plus matching PHPUnit constraints landed in 7.4/8.0, which directly reduces flaky-test debugging time.
• Scraping and content ingestion. Same primitives serve partner-data pulls and content ingestion without a headless browser. Constrain this to JS-free, unauthenticated-or-form-login sources; it has no proxy, fingerprint, or JS execution story.
• Explicit non-decision. This is not a reason to replace Laravel's built-in HTTP test helpers ($this->get(), $this->post(), assertRedirect). Those stay the default for API/JSON assertions. BrowserKit is a narrow addition for flows where "click the Checkout link and submit the form" is the behaviour under test.

Maintenance signal is good, and it matters for planning. Recent releases show active bug-fixing in exactly the areas that cause flaky tests: cookie values containing +, most-specific-cookie matching, PHP 8.6 deprecation fixes, form submission with empty file fields. That is a healthy component, not an abandoned one.

When to Consider This Package

Adopt when:

• You have JS-free, multi-page journeys where the mechanics of navigation (which link, which form field, which redirect) are the thing that breaks.
• Your team is comfortable owning a small, version-locked integration layer and its tests.
• You want journey coverage with no browser fleet, no Node toolchain, and no CI infrastructure to operate.
• You're already carrying Symfony components, or you're willing to take on symfony/dom-crawler and symfony/css-selector — both required for selector-based methods and neither a Laravel default.
• You're on PHP 8.4+ if you want the Symfony 8 line; otherwise pin to 6.4 or 7.x and accept a slower cadence.

Look elsewhere when:

• The flow depends on JavaScript. By design, no JS execution. Client-rendered journeys are invisible to it — use Laravel Dusk, Playwright, or Cypress.
• You need real-browser fidelity — visual regression, cross-browser behaviour, file-picker quirks, timing-sensitive UI.
• You have no spare engineering capacity. If nobody can own the kernel glue, Dusk's batteries-included model is the cheaper total cost despite heavier infrastructure.
• You need a vendor relationship or SLA. Symfony is sponsor-funded; issues live in the monorepo. There is no commercial support contract to escalate to.
• Dependents = 0 in our tooling signals this is used as an internal component of a framework, not a widely-adopted standalone dependency — which is fine, but it means fewer public answers when our glue misbehaves.

Known risk worth putting in the decision record: Symfony 8 enforced return types across components. A glue class written against 7.x can fail to compile on 8.x. Treat our glue as a version-locked artifact with an owner and a scheduled review at each Symfony major.

How to Pitch It (Stakeholders)

To executives: This is a low-cost, low-risk testing capability with zero production blast radius — the entire integration lives under tests/, uses an MIT licence, requires no browser binaries or Node toolchain, and is reversible in an afternoon. The return is developer velocity and regression confidence on our highest-value user journeys, not a user-facing feature. It will not, by itself, fix test coverage; it makes a specific category of coverage — multi-step form and navigation flows — affordable to write and fast to run.

To engineering: You get link clicking, form filling with hidden fields, cookie/session persistence, redirect handling, and history assertions for free. You own one class that bridges BrowserKit to the Laravel kernel, plus its tests. You inherit two real dependencies (dom-crawler, css-selector) and a coupling to Symfony majors that we should pin deliberately. It composes cleanly with PHPUnit and Pest.

The ask: A timeboxed spike — one to two engineer-weeks — to build the glue and port three to five existing journey tests, then compare runtime and flake rate against the status quo (and against Dusk if JS flows are in scope). Decision gate at the end: keep for JS-free journeys, or fold into Dusk and drop the dependency. Do not adopt organisation-wide before that gate.