Guzzle provides several tools that will enable you to easily mock the HTTPlayer without needing to send requests over the internet.
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.
useGuzzleHttp\Client;useGuzzleHttp\Handler\MockHandler;useGuzzleHttp\HandlerStack;useGuzzleHttp\Psr7\Response;useGuzzleHttp\Psr7\Request;useGuzzleHttp\Exception\RequestException;// Create a mock and queue two responses.$mock=newMockHandler([newResponse(200,['X-Foo'=>'Bar'],'Hello, World'),newResponse(202,['Content-Length'=>0]),newRequestException('Error Communicating with Server',newRequest('GET','test'))]);$handlerStack=HandlerStack::create($mock);$client=newClient(['handler'=>$handlerStack]);// The first request is intercepted with the first response.$response=$client->request('GET','/');echo$response->getStatusCode();//> 200echo$response->getBody();//> Hello, World// The second request is intercepted with the second response.echo$client->request('GET','/')->getStatusCode();//> 202// Reset the queue and queue up a new response$mock->reset();$mock->append(newResponse(201));// As the mock was reset, the new response is the 201 CREATED,// instead of the previously queued RequestExceptionecho$client->request('GET','/')->getStatusCode();//> 201
When no more responses are in the queue and a request is sent, anOutOfBoundsException is thrown.
When using things like theMock 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.
useGuzzleHttp\Client;useGuzzleHttp\HandlerStack;useGuzzleHttp\Middleware;$container=[];$history=Middleware::history($container);$handlerStack=HandlerStack::create();// or $handlerStack = HandlerStack::create($mock); if using the Mock handler.// Add the history middleware to the handler stack.$handlerStack->push($history);$client=newClient(['handler'=>$handlerStack]);$client->request('GET','http://httpbin.org/get');$client->request('HEAD','http://httpbin.org/get');// Count the number of transactionsechocount($container);//> 2// Iterate over the requests and responsesforeach($containeras$transaction){echo$transaction['request']->getMethod();//> GET, HEADif($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.}
Using mock responses is almost always enough when testing a web service client.When implementing customHTTP 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.
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 theGuzzleHttp\Tests\Serverclass. If you are using the test server orServer 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 theServer 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 andException objects.
useGuzzleHttp\Client;useGuzzleHttp\Psr7\Response;useGuzzleHttp\Tests\Server;// Start the server and queue a responseServer::enqueue([newResponse(200,['Content-Length'=>0])]);$client=newClient(['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();echocount(Server::received());// 0