Behat Http Mock Context Laravel Package

Technical Evaluation

Architecture fit. The package is a Behat context extension, not a Laravel package. It plugs into Behat's context/step-definition lifecycle to intercept outbound HTTP and return canned responses. Laravel's idiomatic testing stack is PHPUnit/Pest with Http::fake(), which already covers this use case at the framework layer. Adopting this package means adopting Behat as a second test harness — a material architectural addition, not a drop-in.

Integration feasibility. Moderate at best. Laravel has no first-class Behat integration; a FeatureContext must manually bootstrap the application kernel, resolve the container, and manage per-scenario teardown. That bootstrap is the bulk of the work and is entirely outside this package's scope. The critical unknown is how interception happens: if it operates on the Guzzle handler stack, it may compose with Illuminate\Support\Facades\Http (which wraps Guzzle); if it requires injecting its own client or mocking at a higher layer, services using the Http facade will bypass it entirely and silently hit the network.

Technical risk. High, driven by signal quality rather than code quality. Four stars, zero dependents, one release in 2024, and a single vendor (MacPaw) publishing what appears to be an internally-extracted tool. There is no evidence of production use outside the originator. Mitigants: MIT license, small surface area, and a narrow responsibility — all of which make a hard fork viable if the upstream goes quiet. The real risk is not the package dying; it's discovering mid-adoption that coverage is partial.

Key questions to answer in a spike.

• Does it intercept at the Guzzle handler level such that Http::fake()-eligible code paths are covered?
• Are mocks scoped and reset per scenario, or does state leak across a suite?
• Does it fail loudly when an unmatched request is made, or fall through to the real network?
• PHP 8.1/8.2/8.3 and Guzzle 7 support; Behat 3.x only, or current Behat?
• Can it simulate timeouts, connection errors, and malformed bodies — or only status/body pairs?
• Does it expose request assertions (headers, payload) or only response stubbing?

Integration Approach

Stack fit. Poor for a Laravel-first team. Good only under a specific condition: the organization already runs Behat for cross-service or stakeholder-facing acceptance tests (common in polyglot PHP estates with Symfony/Magento components) and wants one mocking vocabulary across suites. Absent that, Http::fake() plus Pest's higher-order expectations is cheaper, better supported, and already known to the team.

Migration path. Do not attempt to replace Pest. Run Behat as an isolated, non-blocking CI job alongside the existing suite. Pin the package version explicitly and vendor/fork it into a private namespace early — the fork cost is trivial now and expensive later. Wrap the package behind your own step definitions (Given the payments API returns a 503) so the mocking backend is swappable without rewriting feature files.

Compatibility. Verify Composer constraints against the target Laravel version, PHP minor, and Guzzle major before anything else. Confirm the Behat version supported and whether the context can coexist with other contexts in the same suite. Test the Laravel bootstrap path on the oldest and newest supported framework versions in the matrix.

Sequencing.

1. Timeboxed spike (3–5 days): prove interception against one real service class that uses the Http facade.
2. Confirm fail-loud behavior on unmatched requests — this is a go/no-go gate.
3. Build the Laravel FeatureContext bootstrap and 5–10 representative step definitions.
4. Stand up the isolated CI job with network egress blocked, so pass-through is impossible rather than merely discouraged.
5. Decide on broader rollout based on steps 1–2, not on step 3's momentum.

Operational Impact

Maintenance. Low code churn, low upstream activity. Budget for owning the fork: dependency bumps on Guzzle/PHP majors will be your responsibility, not the vendor's. The larger maintenance burden is the Behat harness itself — bootstrap code, step library, and fixture management — which will outlive any single package choice.

Support. Effectively none. Zero dependents means no community, no Stack Overflow corpus, no third-party tutorials. Internal expertise must be built and retained deliberately; a single engineer becoming the Behat owner is a bus-factor risk.

Scaling. Feature files scale poorly as a mock-definition surface. Expect step-definition sprawl and duplicated response fixtures within a few months. Plan a response-builder or fixture-registry layer early. Runtime is fine — no network calls — but parallel Behat execution requires strict per-worker mock isolation, which is exactly the area most likely to be under-engineered upstream.

Failure modes, ranked by severity.

1. Silent pass-through — unmatched requests reach staging or production. Flaky, slow, and potentially destructive. Mitigate with egress blocking in CI, not configuration alone.
2. Mock rot — stubbed contracts drift from real APIs; tests stay green while integration breaks. Requires periodic contract validation against a recorded or real endpoint.
3. State leakage between scenarios — order-dependent failures that erode trust in the suite.
4. Coverage gaps — some services bypass interception because they don't use the mocked client path, producing a false sense of safety.
5. Upstream abandonment — survivable via fork, but only if forked before it's needed.

Ramp-up. One to two sprints for a small team to reach productivity, dominated by Behat and Gherkin fluency rather than this package. That is a materially higher onboarding cost than Http::fake(), which most Laravel developers already carry. Weigh it against the actual business value of executable, stakeholder-readable specifications — if nobody outside engineering reads the feature files, the ROI does not clear the bar at a 0.38 score.