REST - Codeception - Documentation

Guides

Testomatio - Test Management for Codeception

Search

REST

Installation

composer require --dev codeception/module-rest

Description

Module for testing REST WebService.

This module requires either PhpBrowser or a framework module (e.g. Symfony, Laravel) to send the actual HTTP request.

Configuration

url optional - the url of api
shortDebugResponse optional - number of chars to limit the API response length

Example

modules:
   enabled:
       - REST:
           depends: PhpBrowser
           url: 'https://example.com/api/v1/'
           shortDebugResponse: 300 # only the first 300 characters of the response

In case you need to configure low-level HTTP headers, that’s done on the PhpBrowser level like so:

modules:
   enabled:
       - REST:
           depends: PhpBrowser
           url: &url 'https://example.com/api/v1/'
   config:
       PhpBrowser:
           url: *url
           headers:
               Content-Type: application/json

JSONPath

JSONPath is the equivalent to XPath, for querying JSON data structures. Here’s an Online JSONPath Expressions Tester

Public Properties

headers - array of headers going to be sent.
params - array of sent data
response - last response (string)

Parts

Json - actions for validating Json responses (no Xml responses)
Xml - actions for validating XML responses (no Json responses)

Conflicts

Conflicts with SOAP module

Actions

amAWSAuthenticated

param array $additionalAWSConfig
throws \Codeception\Exception\ConfigurationException
return void

Allows to send REST request using AWS Authorization

Only works with PhpBrowser Example Config:

yml
modules:
     enabled:
         - REST:
             aws:
                 key: accessKey
                 secret: accessSecret
                 service: awsService
                 region: awsRegion

Code:

<?php
$I->amAWSAuthenticated();

amBearerAuthenticated

part json
part xml
param string $accessToken
return void

Adds Bearer authentication via access token.

amDigestAuthenticated

part json
part xml
param string $username
param string $password
return void

Adds Digest authentication via username/password.

amHttpAuthenticated

part json
part xml
param string $username
param string $password
return void

Adds HTTP authentication via username/password.

amNTLMAuthenticated

part json
part xml
param string $username
param string $password
throws \Codeception\Exception\ModuleException
return void

Adds NTLM authentication via username/password.

Requires client to be Guzzle >=6.3.0 Out of scope for functional modules.

Example:

<?php
$I->amNTLMAuthenticated('jon_snow', 'targaryen');

deleteHeader

@deprecated

param string $name
return void

dontSeeBinaryResponseEquals

part json
part xml
param string $hash the hashed data response expected
param string $algo the hash algorithm to use. Default md5.
return void

Checks if the hash of a binary response is not the same as provided.

<?php
$I->dontSeeBinaryResponseEquals('8c90748342f19b195b9c6b4eff742ded');

Opposite to seeBinaryResponseEquals

dontSeeHttpHeader

part json
part xml
param string $name
param $value
return void

Checks over the given HTTP header and (optionally) its value, asserting that are not there

dontSeeResponseCodeIs

part json
part xml
param int $code
return void

Checks that response code is not equal to provided value.

<?php
$I->dontSeeResponseCodeIs(200);

// preferred to use \Codeception\Util\HttpCode
$I->dontSeeResponseCodeIs(\Codeception\Util\HttpCode::OK);

dontSeeResponseContains

part json
part xml
param string $text
return void

Checks whether last response do not contain text.

dontSeeResponseContainsJson

part json
param array $json
return void

Opposite to seeResponseContainsJson

dontSeeResponseJsonMatchesJsonPath

part json
param string $jsonPath
return void

See #jsonpath for general info on JSONPath.

Opposite to seeResponseJsonMatchesJsonPath()

dontSeeResponseJsonMatchesXpath

part json
param string $xPath
return void

Opposite to seeResponseJsonMatchesXpath

dontSeeResponseJsonXpathEvaluatesTo

part json
param string $xPath
param $expected
return void

Opposite to seeResponseJsonXpathEvaluatesTo

dontSeeResponseMatchesJsonType

part json
see seeResponseMatchesJsonType
param array $jsonType JsonType structure
param ?string $jsonPath
return void

Opposite to seeResponseMatchesJsonType.

dontSeeXmlResponseEquals

part xml
param mixed $xml
return void

Checks XML response does not equal to provided XML.

Comparison is done by canonicalizing both xml`s.

Parameter can be passed either as XmlBuilder, DOMDocument, DOMNode, XML string, or array (if no attributes).

dontSeeXmlResponseIncludes

part xml
param mixed $xml
return void

Checks XML response does not include provided XML.

Comparison is done by canonicalizing both xml`s. Parameter can be passed either as XmlBuilder, DOMDocument, DOMNode, XML string, or array (if no attributes).

dontSeeXmlResponseMatchesXpath

part xml
param string $xPath
return void

Checks whether XML response does not match XPath

<?php
$I->dontSeeXmlResponseMatchesXpath('//root/user[@id=1]');

grabAttributeFromXmlElement

part xml
param string $cssOrXPath
param string $attribute
return string

Finds and returns attribute of element.

Element is matched by either CSS or XPath

grabDataFromResponseByJsonPath

part json
param string $jsonPath
throws \Exception
return array Array of matching items

See #jsonpath for general info on JSONPath.

Even for a single value an array is returned. Example:

<?php
// match the first `user.id` in json
$firstUserId = $I->grabDataFromResponseByJsonPath('$..users[0].id');
$I->sendPut('/user', array('id' => $firstUserId[0], 'name' => 'davert'));

grabHttpHeader

part json
part xml
param string $name
param bool $first Whether to return the first value or all header values
return string|array The first header value if $first is true, an array of values otherwise

Returns the value of the specified header name

grabResponse

part json
part xml
return string

Returns current response so that it can be used in next scenario steps.

Example:

<?php
$user_id = $I->grabResponse();
$I->sendPut('/user', array('id' => $user_id, 'name' => 'davert'));

grabTextContentFromXmlElement

part xml
param mixed $cssOrXPath
return string

Finds and returns text contents of element.

Element is matched by either CSS or XPath

haveHttpHeader

part json
part xml
param string $name
param string $value
return void

Sets a HTTP header to be used for all subsequent requests. Use unsetHttpHeader to unset it.

<?php
$I->haveHttpHeader('Content-Type', 'application/json');
// all next requests will contain this header

haveServerParameter

param $name
param $value
return void

Sets SERVER parameter valid for all next requests.

$I->haveServerParameter('name', 'value');

seeBinaryResponseEquals

part json
part xml
param string $hash the hashed data response expected
param string $algo the hash algorithm to use. Default sha1.
return void

Checks if the hash of a binary response is exactly the same as provided.

Parameter can be passed as any hash string supported by hash(), with an optional second parameter to specify the hash type, which defaults to sha1.

Example: Using sha1 hash key

<?php
$I->seeBinaryResponseEquals('df589122eac0f6a7bd8795436e692e3675cadc3b');

Example: Using sha1 for a file contents

<?php
$fileData = file_get_contents('test_file.jpg');
$I->seeBinaryResponseEquals(md5($fileData));

Example: Using sha256 hash

<?php
$fileData = '/9j/2wBDAAMCAgICAgMCAgIDAwMDBAYEBAQEBAgGBgUGCQgKCgkICQkKDA8MCgsOCwkJDRENDg8QEBEQCgwSExIQEw8QEBD/yQALCAABAAEBAREA/8wABgAQEAX/2gAIAQEAAD8A0s8g/9k='; // very small jpeg
$I->seeBinaryResponseEquals(hash('sha256', base64_decode($fileData)), 'sha256');

seeHttpHeader

part json
part xml
param string $name
param $value
return void

Checks over the given HTTP header and (optionally) its value, asserting that are there

seeHttpHeaderOnce

part json
part xml
param string $name
return void

Checks that http response header is received only once.

HTTP RFC2616 allows multiple response headers with the same name. You can check that you didn’t accidentally sent the same header twice.

<?php
$I->seeHttpHeaderOnce('Cache-Control');

seeResponseCodeIs

part json
part xml
param int $code
return void

Checks response code equals to provided value.

<?php
$I->seeResponseCodeIs(200);

// preferred to use \Codeception\Util\HttpCode
$I->seeResponseCodeIs(\Codeception\Util\HttpCode::OK);

seeResponseCodeIsClientError

part json
part xml
return void

Checks that the response code is 4xx

seeResponseCodeIsRedirection

part json
part xml
return void

Checks that the response code 3xx

seeResponseCodeIsServerError

part json
part xml
return void

Checks that the response code is 5xx

seeResponseCodeIsSuccessful

part json
part xml
return void

Checks that the response code is 2xx

seeResponseContains

part json
part xml
param string $text
return void

Checks whether the last response contains text.

seeResponseContainsJson

part json
param array $json
return void

Checks whether the last JSON response contains provided array.

The response is converted to array with json_decode($response, true) Thus, JSON is represented by associative array. This method matches that response array contains provided array.

Examples:

<?php
// response: {name: john, email: [email protected]}
$I->seeResponseContainsJson(array('name' => 'john'));

// response {user: john, profile: { email: [email protected] }}
$I->seeResponseContainsJson(array('email' => '[email protected]'));

This method recursively checks if one array can be found inside of another.

seeResponseEquals

part json
part xml
param $expected
return void

Checks if response is exactly the same as provided.

seeResponseIsJson

part json
return void

Checks whether last response was valid JSON.

This is done with json_last_error function.

seeResponseIsValidOnJsonSchema

part json
see codecept_absolute_path()
param string $schemaFilename
return void

Checks whether last response matches the supplied json schema (https://json-schema.org/) Supply schema as relative file path in your project directory or an absolute path

seeResponseIsValidOnJsonSchemaString

part json
param string $schema
return void

Checks whether last response matches the supplied json schema (https://json-schema.org/) Supply schema as json string.

Examples:

<?php
// response: {"name": "john", "age": 20}
$I->seeResponseIsValidOnJsonSchemaString('{"type": "object"}');

// response {"name": "john", "age": 20}
$schema = [
 'properties' => [
     'age' => [
         'type' => 'integer',
         'minimum' => 18
     ]
 ]
];
$I->seeResponseIsValidOnJsonSchemaString(json_encode($schema));

seeResponseIsXml

part xml
return void

Checks whether last response was valid XML.

This is done with libxml_get_last_error function.

seeResponseJsonMatchesJsonPath

part json
param string $jsonPath
return void

See #jsonpath for general info on JSONPath.

Checks if JSON structure in response matches JSONPath.

  { "store": {
      "book": [
        { "category": "reference",
          "author": "Nigel Rees",
          "title": "Sayings of the Century",
          "price": 8.95
        },
        { "category": "fiction",
          "author": "Evelyn Waugh",
          "title": "Sword of Honour",
          "price": 12.99
        }
   ],
      "bicycle": {
        "color": "red",
        "price": 19.95
      }
    }
  }

<?php
// at least one book in store has author
$I->seeResponseJsonMatchesJsonPath('$.store.book[*].author');
// first book in store has author
$I->seeResponseJsonMatchesJsonPath('$.store.book[0].author');
// at least one item in store has price
$I->seeResponseJsonMatchesJsonPath('$.store..price');

seeResponseJsonMatchesXpath

part json
param string $xPath
return void

Checks if json structure in response matches the xpath provided.

JSON is not supposed to be checked against XPath, yet it can be converted to xml and used with XPath. This assertion allows you to check the structure of response json. *

  { "store": {
      "book": [
        { "category": "reference",
          "author": "Nigel Rees",
          "title": "Sayings of the Century",
          "price": 8.95
        },
        { "category": "fiction",
          "author": "Evelyn Waugh",
          "title": "Sword of Honour",
          "price": 12.99
        }
   ],
      "bicycle": {
        "color": "red",
        "price": 19.95
      }
    }
  }

<?php
// at least one book in store has author
$I->seeResponseJsonMatchesXpath('//store/book/author');
// first book in store has author
$I->seeResponseJsonMatchesXpath('//store/book[1]/author');
// at least one item in store has price
$I->seeResponseJsonMatchesXpath('/store//price');

seeResponseJsonXpathEvaluatesTo

part json
param string $xPath
param $expected
return void

Checks if applying xpath to json structure in response matches the expected result.

JSON is not supposed to be checked against XPath, yet it can be converted to xml and used with XPath. This assertion allows you to check the structure of response json. *

  { "store": {
      "book": [
        { "category": "reference",
          "author": "Nigel Rees",
          "title": "Sayings of the Century",
          "price": 8.95
        },
        { "category": "fiction",
          "author": "Evelyn Waugh",
          "title": "Sword of Honour",
          "price": 12.99
        }
   ],
      "bicycle": {
        "color": "red",
        "price": 19.95
      }
    }
  }

<?php
// at least one book in store has author
$I->seeResponseJsonXpathEvaluatesTo('count(//store/book/author) > 0', true);
// count the number of books written by given author is 5
$I->seeResponseJsonMatchesXpath("//author[text() = 'Nigel Rees']", 1.0);

seeResponseMatchesJsonType

part json
see JsonType
param array $jsonType
param ?string $jsonPath
return void

Checks that JSON matches provided types.

In case you don’t know the actual values of JSON data returned you can match them by type. It starts the check with a root element. If JSON data is an array it will check all elements of it. You can specify the path in the json which should be checked with JsonPath

Basic example:

<?php
// {'user_id': 1, 'name': 'davert', 'is_active': false}
$I->seeResponseMatchesJsonType([
     'user_id' => 'integer',
     'name' => 'string|null',
     'is_active' => 'boolean'
]);

// narrow down matching with JsonPath:
// {"users": [{ "name": "davert"}, {"id": 1}]}
$I->seeResponseMatchesJsonType(['name' => 'string'], '$.users[0]');

You can check if the record contains fields with the data types you expect. The list of possible data types:

string
integer
float
array (json object is array as well)
boolean
null

You can also use nested data type structures, and define multiple types for the same field:

<?php
// {'user_id': 1, 'name': 'davert', 'company': {'name': 'Codegyre'}}
$I->seeResponseMatchesJsonType([
     'user_id' => 'integer|string', // multiple types
     'company' => ['name' => 'string']
]);

You can also apply filters to check values. Filter can be applied with a : char after the type declaration, or after another filter if you need more than one.

Here is the list of possible filters:

array:empty - check that value is an empty array
integer:>{val} - checks that integer is greater than {val} (works with float and string types too).
integer:<{val} - checks that integer is lower than {val} (works with float and string types too).
string:url - checks that value is valid url.
string:date - checks that value is date in JavaScript format: https://weblog.west-wind.com/posts/2014/Jan/06/JavaScript-JSON-Date-Parsing-and-real-Dates
string:email - checks that value is a valid email according to https://emailregex.com/
string:regex({val}) - checks that string matches a regex provided with {val}

This is how filters can be used:

<?php
// {'user_id': 1, 'email' => '[email protected]'}
$I->seeResponseMatchesJsonType([
     'user_id' => 'string:>0:<1000', // multiple filters can be used
     'email' => 'string:regex(~\@~)' // we just check that @ char is included
]);

// {'user_id': '1'}
$I->seeResponseMatchesJsonType([
     'user_id' => 'string:>0', // works with strings as well
]);

You can also add custom filters by using {@link JsonType::addCustomFilter()}. See JsonType reference.

seeXmlResponseEquals

part xml
param mixed $xml
return void

Checks XML response equals provided XML.

Comparison is done by canonicalizing both xml`s.

Parameters can be passed either as DOMDocument, DOMNode, XML string, or array (if no attributes).

seeXmlResponseIncludes

part xml
param mixed $xml
return void

Checks XML response includes provided XML.

Comparison is done by canonicalizing both xml`s. Parameter can be passed either as XmlBuilder, DOMDocument, DOMNode, XML string, or array (if no attributes).

Example:

<?php
$I->seeXmlResponseIncludes('<result>1</result>');

seeXmlResponseMatchesXpath

part xml
param string $xPath
return void

Checks whether XML response matches XPath

<?php
$I->seeXmlResponseMatchesXpath('//root/user[@id=1]');

send

part json
part xml
param string $method
param string $url
param array|string|\JsonSerializable $params
param array $files

Sends a HTTP request.

sendDelete

part json
part xml
param string $url
param array $params
param array $files

Sends DELETE request to given uri.

<?php
$I->sendDelete('/message/1');

sendGet

part json
part xml
param string $url
param array $params

Sends a GET request to given uri.

<?php
$response = $I->sendGet('/users');

// send get with query params
$I->sendGet('/orders', ['id' => 1])

sendHead

part json
part xml
param string $url
param array $params

Sends a HEAD request to given uri.

sendLink

link https://tools.ietf.org/html/rfc2068#section-19.6.2.4
part json
part xml
author [email protected]
param string $url
param array $linkEntries (entry is array with keys “uri” and “link-param”)
return void

Sends LINK request to given uri.

sendOptions

part json
part xml
param string $url
param array $params
return void

Sends an OPTIONS request to given uri.

sendPatch

part json
part xml
param string $url
param array|string|\JsonSerializable $params
param array $files

Sends PATCH request to given uri.

<?php
$response = $I->sendPatch('/message/1', ['subject' => 'Read this!']);

sendPost

part json
part xml
see https://php.net/manual/en/features.file-upload.post-method.php
see codecept_data_dir()
param string $url
param array|string|\JsonSerializable $params
param array $files A list of filenames or “mocks” of $_FILES (each entry being an array with the following keys: name, type, error, size, tmp_name (pointing to the real file path). Each key works as the “name” attribute of a file input field.

Sends a POST request to given uri. Parameters and files can be provided separately.

Example:

<?php
//simple POST call
$response = $I->sendPost('/message', ['subject' => 'Read this!', 'to' => '[email protected]']);
//simple upload method
$I->sendPost('/message/24', ['inline' => 0], ['attachmentFile' => codecept_data_dir('sample_file.pdf')]);
//uploading a file with a custom name and mime-type. This is also useful to simulate upload errors.
$I->sendPost('/message/24', ['inline' => 0], [
    'attachmentFile' => [
         'name' => 'document.pdf',
         'type' => 'application/pdf',
         'error' => UPLOAD_ERR_OK,
         'size' => filesize(codecept_data_dir('sample_file.pdf')),
         'tmp_name' => codecept_data_dir('sample_file.pdf')
    ]
]);
// If your field names contain square brackets (e.g. `<input type="text" name="form[task]">`),
// PHP parses them into an array. In this case you need to pass the fields like this:
$I->sendPost('/add-task', ['form' => [
    'task' => 'lorem ipsum',
    'category' => 'miscellaneous',
]]);

sendPut

part json
part xml
param string $url
param array|string|\JsonSerializable $params
param array $files

Sends PUT request to given uri.

<?php
$response = $I->sendPut('/message/1', ['subject' => 'Read this!']);

sendUnlink

link https://tools.ietf.org/html/rfc2068#section-19.6.2.4
part json
part xml
author [email protected]
param string $url
param array $linkEntries (entry is array with keys “uri” and “link-param”)
return void

Sends UNLINK request to given uri.

setServerParameters

param array $params
return void

Sets SERVER parameters valid for all next requests.

this will remove old ones.

$I->setServerParameters([]);

startFollowingRedirects

part xml
part json
return void

Enables automatic redirects to be followed by the client

<?php
$I->startFollowingRedirects();

stopFollowingRedirects

part xml
part json
return void

Prevents automatic redirects to be followed by the client

<?php
$I->stopFollowingRedirects();

unsetHttpHeader

part json
part xml
param string $name the name of the header to unset.
return void

Unsets a HTTP header (that was originally added by haveHttpHeader()), so that subsequent requests will not send it anymore.

Example:

<?php
$I->haveHttpHeader('X-Requested-With', 'Codeception');
$I->sendGet('test-headers.php');
// ...
$I->unsetHttpHeader('X-Requested-With');
$I->sendPost('some-other-page.php');

Module reference is taken from the source code. Help us to improve documentation. Edit module reference

Don't know how to write tests on your own? We will build or improve them for you. Request a quote for official enterprise support or trainings

❤️ Support us on OpenCollective!

Testomatio - Test Management for Codeception

Codeception is a BDD-styled PHP testing framework, brought to you by Codeception Team. OpenSource MIT Licensed.

Design made by Awesomic

Sunbelt Computer Software

PL/B Language Development and Support

Guides

Modules

Reference

Util Classes

Guides

Search

REST

Installation

Description

Configuration

Example

JSONPath

Public Properties

Parts

Conflicts

Actions

amAWSAuthenticated

amBearerAuthenticated

amDigestAuthenticated

amHttpAuthenticated

amNTLMAuthenticated

deleteHeader

dontSeeBinaryResponseEquals

dontSeeHttpHeader

dontSeeResponseCodeIs

dontSeeResponseContains

dontSeeResponseContainsJson

dontSeeResponseJsonMatchesJsonPath

dontSeeResponseJsonMatchesXpath

dontSeeResponseJsonXpathEvaluatesTo

dontSeeResponseMatchesJsonType

dontSeeXmlResponseEquals

dontSeeXmlResponseIncludes

dontSeeXmlResponseMatchesXpath

grabAttributeFromXmlElement

grabDataFromResponseByJsonPath

grabHttpHeader

grabResponse

grabTextContentFromXmlElement

haveHttpHeader

haveServerParameter

seeBinaryResponseEquals

seeHttpHeader

seeHttpHeaderOnce

seeResponseCodeIs

seeResponseCodeIsClientError

seeResponseCodeIsRedirection

seeResponseCodeIsServerError

seeResponseCodeIsSuccessful

seeResponseContains

seeResponseContainsJson

seeResponseEquals

seeResponseIsJson

seeResponseIsValidOnJsonSchema

seeResponseIsValidOnJsonSchemaString

seeResponseIsXml

seeResponseJsonMatchesJsonPath

seeResponseJsonMatchesXpath

seeResponseJsonXpathEvaluatesTo

seeResponseMatchesJsonType

seeXmlResponseEquals

seeXmlResponseIncludes

seeXmlResponseMatchesXpath

send

sendDelete

sendGet

sendHead

sendLink

sendOptions

sendPatch

sendPost

sendPut

sendUnlink

setServerParameters

startFollowingRedirects

stopFollowingRedirects

unsetHttpHeader

Codeception_