Response Expectations

The Http Client offers the possibility to "assert" a response's Http Status Code, headers or payload, should you require it. In this section, the expect() method is introduced.

• Status Code Expectations
  • Expect Http Status Code
  • Otherwise Callback
  • Range of Status Codes
• Advanced Expectations
  • Validate Headers or Payload
  • Multiple Expectations
  • Response Manipulation

Status Code Expectations

Expect Http Status Code

In order to assert that a received response has a specific Http Status Code, e.g. 200 OK, state your expected/desired status code, as the first argument for the expect() method.

use Teapot\StatusCode;

$response = $client
        ->expect(StatusCode::OK)
        ->get('/users');

If the received response's status code does not match, then an ExpectationNotMetException will be thrown.

Otherwise Callback

The ExpectationNotMetException is thrown when the expected status code does not match the received status code. However, this is only intended as a "boilerplate" exception. Most likely, you want to throw your own exception. Therefore, when you provide a callable as the second argument, then the ExpectationNotMetException is not thrown. The provided callback is invoked instead.

use Teapot\StatusCode;
use Aedart\Contracts\Http\Clients\Responses\Status;
use Acme\Exceptions\BadResponse;

$response = $client
        ->expect(StatusCode::OK, function(Status $status){
            throw new BadResponse('Bad response received: ' . (string) $status);
        })
        ->get('/users');

The callback argument is provided with the following arguments, in the given order:

• Status: A wrapper for the received response's http status code and phrase.
• ResponseInterface: The received response (PSR-7).
• RequestInterface: The sent request (PSR-7).

Range of Status Codes

The expect() method also accepts a range of status codes. If the received status code matches one of the expected codes, then the response is considered valid. Should it not match, then either the ExpectationNotMetException is thrown, or the callback is invoked (if provided).

use Teapot\StatusCode;
use Aedart\Contracts\Http\Clients\Responses\Status;
use Acme\Exceptions\BadResponse;

$response = $client
        ->expect([StatusCode::OK, StatusCode::NO_CONTENT], function(Status $status){
            throw new BadResponse('Bad response received: ' . (string) $status);
        })
        ->get('/users');

Advanced Expectations

Validate Headers or Payload

In situations when you need to assert more than the received status code, then you can provide a callable as the first argument. Doing so, will allow you to perform whatever validation logic you may require, upon the received response.

use Aedart\Contracts\Http\Clients\Responses\Status;
use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
use Acme\Exceptions\BadResponse;

$response = $client
        ->expect(function(
            Status $status,
            ResponseInterface $response,
            RequestInterface $request
        ){
            if( ! $response->hasHeader('user_id')){
                throw new BadResponse('Missing user id');
            }
            
            // ... other response validation - not shown...

            if( ! $status->isSuccessful()){
                throw new BadResponse('Bad response received: ' . (string) $status);
            }
        })
        ->get('/users');

Multiple Expectations

There is no limit to the amount of expectations that you may add for a response. Thus, you can add multiple expectations via the the expect() method. They will be executed in the same order as you add them.

use Aedart\Contracts\Http\Clients\Responses\Status;
use Psr\Http\Message\ResponseInterface;
use Teapot\StatusCode;
use Acme\Exceptions\BadResponse;

$response = $client
        // Expect status code...
        ->expect(StatusCode::OK, function(Status $status){
            throw new BadResponse('Bad response received: ' . (string) $status);
        })
    
        // Expect http header...
        ->expect(function(Status $status, ResponseInterface $response){
            if( ! $response->hasHeader('user_id')){
                throw new BadResponse('Missing user id');
            }
        })

        // Expect payload...
        ->expect(function(Status $status, ResponseInterface $response){
            $content = $response->getBody()->getContents();
            $response->getBody()->rewind();

            $decoded = json_decode($content);
            if(empty($decoded) || json_last_error() !== JSON_ERROR_NONE){
                throw new BadResponse('Payload is invalid');
            }
        })
        ->get('/users');

Array of Callbacks

If you expectations start to get bulky or lengthy, then you should extract them into their own methods. You can add them via an array, using the withExpectations() method. How you choose to extract expectation logic, is entirely up to you.

$response = $client
        ->withExpectations([
            [$this, 'expectOkStatus'],
            $expectUserIdCallback,
            // ...etc
        ])
        ->get('/users');

Response Manipulation

The expect() method is not design nor intended to manipulate the received response. This falls outside the scope of the given method. It's only purpose is to allow status code and response validation.