Testing Guzzle Clients
Guzzle provides several tools that will enable you to easily mock the HTTPlayer without needing to send requests over the internet.
- Mock handler
- History middleware
- Node.js web server for integration testing
Mock Handler
When testing HTTP clients, you often need to simulate specific scenarios likereturning a successful response, returning an error, or returning specificresponses in a certain order. Because unit tests need to be predictable, easyto 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 witha response or exception by shifting return values off of a queue.
- use GuzzleHttp\Client;
- use GuzzleHttp\Handler\MockHandler;
- use GuzzleHttp\HandlerStack;
- use GuzzleHttp\Psr7\Response;
- use GuzzleHttp\Psr7\Request;
- use GuzzleHttp\Exception\RequestException;
- // Create a mock and queue two responses.
- $mock = new MockHandler([
- new Response(200, ['X-Foo' => 'Bar']),
- new Response(202, ['Content-Length' => 0]),
- new RequestException("Error Communicating with Server", new Request('GET', 'test'))
- ]);
- $handler = HandlerStack::create($mock);
- $client = new Client(['handler' => $handler]);
- // The first request is intercepted with the first response.
- echo $client->request('GET', '/')->getStatusCode();
- //> 200
- // The second request is intercepted with the second response.
- echo $client->request('GET', '/')->getStatusCode();
- //> 202
When no more responses are in the queue and a request is sent, anOutOfBoundsException
is thrown.
History Middleware
When using things like the Mock
handler, you often need to know if therequests you expected to send were sent exactly as you intended. While the mockhandler responds with mocked responses, the history middleware maintains ahistory of the requests that were sent by a client.
- use GuzzleHttp\Client;
- use GuzzleHttp\HandlerStack;
- use GuzzleHttp\Middleware;
- $container = [];
- $history = Middleware::history($container);
- $stack = HandlerStack::create();
- // Add the history middleware to the handler stack.
- $stack->push($history);
- $client = new Client(['handler' => $stack]);
- $client->request('GET', 'http://httpbin.org/get');
- $client->request('HEAD', 'http://httpbin.org/get');
- // Count the number of transactions
- echo count($container);
- //> 2
- // Iterate over the requests and responses
- foreach ($container as $transaction) {
- echo $transaction['request']->getMethod();
- //> GET, HEAD
- if ($transaction['response']) {
- echo $transaction['response']->getStatusCode();
- //> 200, 200
- } elseif ($transaction['error']) {
- echo $transaction['error'];
- //> exception
- }
- var_dump($transaction['options']);
- //> dumps the request options of the sent request.
- }
Test Web Server
Using mock responses is almost always enough when testing a web service client.When implementing custom HTTP handlers, you'llneed to send actual HTTP requests in order to sufficiently test the handler.However, a best practice is to contact a local web server rather than a serverover the internet.
- Tests are more reliable
- Tests do not require a network connection
- Tests have no external dependencies
Using the test server
Warning
The following functionality is provided to help developers of Guzzledevelop HTTP handlers. There is no promise of backwards compatibilitywhen it comes to the node.js test server or the GuzzleHttp\Tests\Server
class. If you are using the test server or Server
class outside ofguzzlehttp/guzzle, then you will need to configure autoloading andensure the web server is started manually.
Hint
You almost never need to use this test web server. You should only everconsider using it when developing HTTP handlers. The test web serveris not necessary for mocking requests. For that, please use theMock handler and history middleware.
Guzzle ships with a node.js test server that receives requests and returnsresponses from a queue. The test server exposes a simple API that is used toenqueue responses and inspect the requests that it has received.
Any operation on the Server
object will ensure thatthe server is running and wait until it is able to receive requests beforereturning.
GuzzleHttp\Tests\Server
provides a static interface to the test server. Youcan queue an HTTP response or an array of responses by callingServer::enqueue()
. This method accepts an array ofPsr\Http\Message\ResponseInterface
and Exception
objects.
- use GuzzleHttp\Client;
- use GuzzleHttp\Psr7\Response;
- use GuzzleHttp\Tests\Server;
- // Start the server and queue a response
- Server::enqueue([
- new Response(200, ['Content-Length' => 0])
- ]);
- $client = new Client(['base_uri' => Server::$url]);
- echo $client->request('GET', '/foo')->getStatusCode();
- // 200
When a response is queued on the test server, the test server will remove anypreviously queued responses. As the server receives requests, queued responsesare dequeued and returned to the request. When the queue is empty, the serverwill return a 500 response.
You can inspect the requests that the server has retrieved by callingServer::received()
.
- foreach (Server::received() as $response) {
- echo $response->getStatusCode();
- }
You can clear the list of received requests from the web server using theServer::flush()
method.
- Server::flush();
- echo count(Server::received());
- // 0