Client Integration Tests Laravel Package

Product Decisions This Supports

• Build vs. buy for HTTP client infrastructure. If any team owns or forks a PSR-18 client, an internal HTTP abstraction layer, or a custom Guzzle/Symfony handler stack, this package converts "write our own conformance suite" into "adopt a maintained one." That is a decision about weeks of engineering time versus a require-dev line and a CI job.
• Vendor and adapter selection (bake-offs). When comparing Guzzle, Symfony HttpClient, php-http/curl-client, or a newer PSR-18 implementation, this package provides an objective, standards-anchored scorecard instead of opinion-driven review. The output is a pass/fail matrix a PM can put in a decision memo.
• Client migration and upgrade roadmaps. Moving between HTTP clients, pinning an adapter fork, or upgrading a major version is a roadmap item with real blast radius. Running this suite before and after gives a go/no-go signal on behavior changes (redirects, auth, streaming, header semantics, timeouts).
• Risk posture on third-party adoption. Before approving a new low-star HTTP client dependency, running conformance tests is a cheap due-diligence gate. It is a procurement/approval input, not a shipping feature.
• Test strategy boundaries. This package explicitly does not replace Laravel's Http::fake(), Http::preventStrayRequests(), or contract tests against our own APIs. Making that boundary explicit in an RFC is itself a decision — it prevents scope creep into application test suites and keeps the app teams' test layers clean.
• Use cases it does not support (equally a decision): application-level HTTP mocking, load/performance testing, API contract verification against partner services, end-to-end customer journey testing. If a stakeholder asks for any of these, this is the wrong tool and the PM should redirect the request.

When to Consider This Package

Adopt only when all of the following hold:

• You own, wrap, or fork a PSR-18 HTTP client implementation. No custom client means no seam — this is a no-op, stop here.
• You need standards conformance (PSR-18 / PSR-7 / PSR-17, optionally HTTPlug) rather than application behavior testing.
• You can run a local server process in CI (vendor/bin/http_test_server, default port 8080) and have an owner for that job. An unowned CI job becomes a flaky orphan within two quarters.
• You can pin the package and PHPUnit together, and accept an upgrade task whenever the PHPUnit major moves. The suite's test classes are runtime-coupled to PHPUnit; the "PHPUnit > 9" constraint is a nominal claim, not a verified guarantee on PHPUnit 10/11 or Pest. Budget a spike, not a docs read.
• You are prepared to verify offline capability. Changelog history shows a prior reversal back to httpbin.org; anywhere public-network egress appears in CI introduces availability and rate-limit failure modes outside our control.
• You accept running with --exclude-group async unless you genuinely ship an async transport — async coverage depends on ext-uv/ReactPHP, so the "~100 tests" headline is an upper bound.

Look elsewhere when:

• The stack is a standard Laravel application using Illuminate\Support\Facades\Http. Guzzle is already validated upstream; the marginal value here is near zero.
• You need mocking or faking — use Http::fake(), Http::preventStrayRequests(), or php-http/mock-client.
• You need a fast, hermetic unit test suite. This is a network-and-process suite and will be slower and more brittle by design.
• Nobody will own the pin and the CI job. Do not adopt tooling that has no named maintainer.
• The supply-chain signals are unresolved. 16 stars and 0 listed dependents are weak adoption evidence (likely metadata unreliability rather than absence of use), and a future-dated last release is a data-quality red flag in the scoring pipeline. That does not imply a bad package, but it means these repository metrics must not be treated as verified. Confirm the actual latest tag and commit history on Packagist/GitHub before any approval or procurement decision.

How to Pitch It (Stakeholders)

To executives (one paragraph). This is a small, MIT-licensed, dev-only test suite that proves an HTTP client implementation actually behaves correctly against the PSR-18 standard. It ships a local test server and roughly a hundred scenario checks, and never touches production — it is a require-dev dependency with zero runtime footprint. Its value is narrow but real: it turns "which HTTP client should we use, and is upgrading safe?" from a judgment call into a scored, repeatable test. It is not a feature, not a customer-facing change, and not a replacement for our existing application tests. Recommend a timeboxed one-to-two-day evaluation spike, owned by platform engineering, with a clear go/no-go: does our target PHPUnit version actually run these tests cleanly, and can we run them fully offline in CI? If either answer is no, we decline and lose nothing. Risks to note: single-organization, volunteer-driven maintenance (bus factor is the real risk, not code quality), weak adoption signals, and one repository metric that appears unreliable. All are manageable for a dev-only tool, none are acceptable for a production dependency — which is why the dev-only scoping is the whole point.

To engineering leads. The pitch is standardization and regression gating, not coverage. One subclass, one PHPUnit testsuite, one CI job, one pinned version — and you get an objective conformance result for your configured client stack (inject your retries/logging/auth middleware via getOptions() so you test what you actually ship, not a bare client). The honest costs: a local server process on port 8080 in containers, PHPUnit major-version coupling that surfaces as runtime breakage rather than a Composer conflict, a hard break at 4.0.0 for anyone sub-classing against 3.x ($messageFactory replaced by $requestFactory/$streamFactory), and an async story that in practice means --exclude-group async. Ask two questions before writing code: do we actually own a PSR-18 client, and is the target PHPUnit major supported in fact rather than by constraint? Answer those in a spike, not a design doc, then either adopt with a named owner and an upgrade task attached to every future PHPUnit bump — or walk away with a one-paragraph rationale on file.