Expectations

Expectations are constraints that requests must meet to return the right response.

methodIs

It expects for a method.

$builder
    ->when()
        ->methodIs('POST')
    ->then()
        ...

pathIs

It expects for a path.

$builder
    ->when()
        ->pathIs('/v1/products')
    ->then()
        ...

pathMatch

It expects for a path pattern.

$builder
    ->when()
        ->pathMatch('/v1\/products\/[0-9]+/')
    ->then()
        ...

queryParamIs

It expects for a query parameter with specific value (for example term=bluebird).

$builder
    ->when()
        ->queryParamIs('page', '5')
    ->then()
        ...

queryParamExists

It expects a query parameter exists.

$builder
    ->when()
        ->queryParamExists('pages')
    ->then()
        ...

queryParamNotExist

It expects a query parameter does not exists.

$builder
    ->when()
        ->queryParamNotExist('pages')
    ->then()
        ...

queryParamsAre

It expects query parameters with specific values.

$builder
    ->when()
        ->queryParamsAre([
            'pages' => '30',
            'npage' => '5'
        ])
    ->then()
        ...

queryParamsExist

It expects the query parameters exists.

$builder
    ->when()
        ->queryParamsExist([
            'pages',
            'npage'
        ])
    ->then()
        ...

queryParamsNotExist

It expects query parameters does not exist.

$builder
    ->when()
        ->queryParamsNotExist([
            'pages',
            'npage'
        ])
    ->then()
        ...

headerIs

It expects a header with specific value (for example Content-Type: text/html).

$builder
    ->when()
        ->headerIs('Content-Type', 'text/html')
    ->then()
        ...

headerIsNot

It expects a header with non-specific value (for example Content-Type different of text/html).

$builder
    ->when()
        ->headerIsNot('Content-Type', 'text/html')
    ->then()
        ...

headerExists

It expects a header exists.

$builder
    ->when()
        ->headerExists('Authorization')
    ->then()
        ...

headerNotExist

It expects a header does not exist.

$builder
    ->when()
        ->headerNotExist('Authorization')
    ->then()
        ...

headersAre

It expects headers with specific values.

$builder
    ->when()
        ->headersAre([
            'Authorization' => 'Bearer YourToken',
            'Content-Type' => 'application/json'
        ])
    ->then()
        ...

headersExist

It expects headers exist.

$builder
    ->when()
        ->headersExist([
            'Authorization',
            'Content-Type'
        ])
    ->then()
        ...

headersNotExist

It expects headers does not exist.

$builder
    ->when()
        ->headersNotExist([
            'Authorization',
            'Content-Type'
        ])
    ->then()
        ...

body

This feature is available from v1.1.0

The body expectation defines a callback using the string body of the request. It's a flexible way to define your own expectation. For instance, you can check if a json field exists in a request as follows.

$builder
    ->when()
        ->body(function ($body) {
            $json = json_decode($body, true);

            return !isset($json['id']);
        })
    ->then()
        ...

request

This feature is available from v1.1.0

The request expectation defines a callback using the PSR request interface. This is the most flexible way to define an expectation as you can access the whole request object. For instance, you can check if a header value is equal to some value.

$builder
    ->when()
        ->request(function (RequestInterface $request) {
            $contentType = $request->getHeader('Content-Type');
            return $contentType === 'application/json';
        })
    ->then()
        ...

Keep in mind if you're using the Guzzle client, the implementation for RequestInterface will be GuzzleHttp\Psr7\Request. That object returns an array when you execute the method getHeader(), so you must shift this array or get the first element.

return $contentType[0] === 'application/json';

Note we can also perform the above expectation using headerIs.

$builder
    ->when()
        ->headerIs('Content-Type', 'application/json')
    ->then()
        ...

Besides this, you can perform other checks with query parameters, body contents, and more. For instance, you can check if a json field exists in the requests as follows.

$builder
    ->when()
        ->request(function (RequestInterface $request) {
            $stream = $request->getBody();
            $stream->rewind();
            $body = $stream->getContents();

            $json = json_decode($body, true);

            return !isset($json['id']);
        })
    ->then()
        ...

Again, if you're using the Guzzle client, you must rewind the body stream to get the contents.

In this case, is a better idea to use the body expectation instead of the request expectation, but this example show you how flexible is this expectation.