Client Integration Tests Laravel Package

Getting Started

This package provides a shared suite of integration tests for PHP HTTP clients, ensuring compliance with the PSR-18 HTTP client interface and_HTTP Message interfaces. To get started:

1. Require it in your project’s require-dev: composer require --dev php-http/client-integration-tests
2. Create a test class that extends Http\Client\Tests\IntegrationTestCase
3. Implement the abstract createClient() method to return an instance of your HTTP client (e.g., Guzzle, CurlHttpClient)
4. Run the integration suite with phpunit — it will automatically execute ~100+ tests validating standard client behavior, async support, streaming, and edge cases

First use case: verifying your custom or third-party PSR-18 client implementation behaves correctly across realistic HTTP scenarios (redirects, authentication, timeouts, etc.)

Implementation Patterns

• Client Validation: Use it as a gatekeeping suite for new client releases or internal wrappers (e.g., after implementing a custom PSR-18 client or integrating a new HTTP library)
• CI Integration: Add it to your CI pipeline to prevent regressions in client behavior across versions
• Custom Handler Testing: Override the getOptions() method to inject custom handler stacks or middleware (e.g., retry middleware, logging) to test integration with middleware enabled
• Extending Test Cases: Extend IntegrationTestCase to add domain-specific assertions (e.g., assert caching behavior, header transformations) without losing the core compliance suite
• Multi-client Testing: Maintain multiple test classes, each using createClient() to instantiate different client implementations (e.g., one for Guzzle 7, one for Symfony HttpClient), ensuring parity across adapters

Gotchas and Tips

• Missing Mock Server: The suite relies on a local test HTTP server (localhost:8080 by default); ensure no firewall blocks port 8080 or consider customizing getServerUrl() or using setServerUrl() in your test bootstrap
• PHP Version Constraints: Some tests (e.g., async) require ext-uv or ext-reactphp; run tests with --exclude-group async if dependencies are unavailable
• Timeouts & Flakiness: Integration tests may be flaky on slow CI; increase default timeout via clientOptions in setUp() or adjust via environment variables (HTTP_CLIENT_TEST_TIMEOUT)
• Debugging Failures: Enable verbose output with -vvv; most failures include the exact request/response trace (URI, headers, body) — inspect logs for mismatches in PSR-7 message semantics (e.g., headers-as-array vs string)
• Not for Unit Testing: This package is not a mocking library — it’s for black-box integration testing. Use php-http/mock-client or symfony/http-client-contracts test helpers for unit-level mocks
• Version Syncing: Lock the package version alongside your HTTP client to avoid unexpected test breakage when server behavior evolves; check CHANGELOG for test suite additions/deprecations