Mock Handler

When testing HTTP clients, you often need to simulate specific scenarios like returning a successful response, returning an error, or returning specific responses in a certain order. Because unit tests need to be predictable, easy to bootstrap, and fast, hitting an actual remote API is a test smell.

Guzzle provides a mock handler that can be used to fulfill HTTP requests with a response or exception by shifting return values off of a queue.

  1. use GuzzleHttp\Client;
  2. use GuzzleHttp\Handler\MockHandler;
  3. use GuzzleHttp\HandlerStack;
  4. use GuzzleHttp\Psr7\Response;
  5. use GuzzleHttp\Psr7\Request;
  6. use GuzzleHttp\Exception\RequestException;
  8. // Create a mock and queue two responses.
  9. $mock = new MockHandler([
  10.     new Response(200, ['X-Foo' => 'Bar'], 'Hello, World'),
  11.     new Response(202, ['Content-Length' => 0]),
  12.     new RequestException('Error Communicating with Server', new Request('GET', 'test'))
  13. ]);
  15. $handlerStack = HandlerStack::create($mock);
  16. $client = new Client(['handler' => $handlerStack]);
  18. // The first request is intercepted with the first response.
  19. $response = $client->request('GET', '/');
  20. echo $response->getStatusCode();
  21. //> 200
  22. echo $response->getBody();
  23. //> Hello, World
  24. // The second request is intercepted with the second response.
  25. echo $client->request('GET', '/')->getStatusCode();
  26. //> 202
  28. // Reset the queue and queue up a new response
  29. $mock->reset();
  30. $mock->append(new Response(201));
  32. // As the mock was reset, the new response is the 201 CREATED,
  33. // instead of the previously queued RequestException
  34. echo $client->request('GET', '/')->getStatusCode();
  35. //> 201

When no more responses are in the queue and a request is sent, an OutOfBoundsException is thrown.