Mock Client Laravel Package

Getting Started

1. Install via Composer: composer require --dev php-http/mock-client.
2. Instantiate MockClient and optionally inject a MessageFactory (e.g., from nyholm/psr7 or guzzlehttp/psr7) for creating responses/requests.
3. Queue mock responses using addResponse() or addException() in the order they’ll be consumed.
4. Inject the MockClient into your service (e.g., where a PSR-18/HTTPlug client is type-hinted).
5. In your test, execute the HTTP-dependent code and assert against the sent requests via getRequests() or verify response behavior.

First use case: Unit-testing a service that sends an API request—verify it formats the request correctly and handles a mocked success response.

Implementation Patterns

• Test State Isolation: Create a fresh MockClient instance per test to avoid cross-test contamination.
• Queue Behavior: Chain addResponse() calls to simulate sequences (e.g., retry logic: first request fails with 503 → second succeeds).
• Request Assertions: After invoking client logic, call getRequests() to inspect headers, method, URI, and body—assert on actual HTTP semantics.
• Exception Simulation: Use addException(new \Http\Client\NetworkException(...)) to test error handling paths (e.g., retries, fallbacks).
• Integration with Factories: Pair with HttplugClientFactory or DI containers to inject mock clients into Symfony/Laravel services only in test environments.
• Test-Driven Development (TDD): Define behavior first ($mock->addResponse(...)), then implement client logic—validate compliance via getRequests().

Gotchas and Tips

• No Auto-Reset: getRequests() retains all sent requests until manually cleared (no built-in reset)—use getRequests() before assertions, and avoid sharing instances across unrelated test phases.
• Request Order Matters: Responses/exceptions are consumed FIFO; mis-ordered queuing causes LogicException. Validate queue length matches expected calls.
• Factory Dependency: You must inject a compatible MessageFactory (e.g., Symfony’s Symfony\Component\HttpClient\Psr18Client won’t work directly—use nyholm/psr7 or php-http/discovery strategies).
• PSR-18 vs HTTPlug: Works seamlessly with PSR-18 clients; for HTTPlug, ensure you’re using Http\Client\HttpClient (v2) and not deprecated v1 interfaces.
• Extensibility: Extend MockClient to add helper methods like expectGet($uri) that queue and assert on expected endpoints, streamlining test readability.
• Debugging Tip: Print last request via (string)$mock->getLastRequest()->getUri() when failures are subtle—this helps compare against test expectations.