| layout | doc |
|---|---|
| title | REST - Codeception - Documentation |
If you use Codeception installed using composer, install this module with the following command:
{% highlight yaml %} composer require --dev codeception/module-rest
{% endhighlight %}
Alternatively, you can enable REST module in suite configuration file and run
{% highlight yaml %} codecept init upgrade4
{% endhighlight %}
This module was bundled with Codeception 2 and 3, but since version 4 it is necessary to install it separately.
Some modules are bundled with PHAR files.
Warning. Using PHAR file and composer in the same project can cause unexpected errors.
Module for testing REST WebService.
This module requires either PhpBrowser or a framework module (e.g. Symfony, Laravel) to send the actual HTTP request.
urloptional - the url of apishortDebugResponseoptional - number of chars to limit the API response length
{% highlight yaml %}
modules: enabled: - REST: depends: PhpBrowser url: 'https://example.com/api/v1/' shortDebugResponse: 300 # only the first 300 characters of the response
{% endhighlight %}
In case you need to configure low-level HTTP headers, that's done on the PhpBrowser level like so:
{% highlight yaml %}
modules: enabled: - REST: depends: PhpBrowser url: &url 'https://example.com/api/v1/' config: PhpBrowser: url: *url headers: Content-Type: application/json
{% endhighlight %}
JSONPath is the equivalent to XPath, for querying JSON data structures. Here's an Online JSONPath Expressions Tester
- headers - array of headers going to be sent.
- params - array of sent data
- response - last response (string)
- Json - actions for validating Json responses (no Xml responses)
- Xml - actions for validating XML responses (no Json responses)
Conflicts with SOAP module
param array$additionalAWSConfigthrows ConfigurationExceptionreturn void
Allows to send REST request using AWS Authorization
Only works with PhpBrowser Example Config: {% highlight yaml %} yml modules: enabled: - REST: aws: key: accessKey secret: accessSecret service: awsService region: awsRegion
{% endhighlight %} Code: {% highlight php %}
amAWSAuthenticated(); {% endhighlight %} #### 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 ModuleException` * `return void` Adds NTLM authentication via username/password. Requires client to be Guzzle >=6.3.0 Out of scope for functional modules. Example: {% highlight php %} amNTLMAuthenticated('jon_snow', 'targaryen'); {% endhighlight %} #### deleteHeader * `part` json * `part` xml * `param string` $name the name of the header to delete. * `return void` Deletes a HTTP header (that was originally added by [haveHttpHeader()](#haveHttpHeader)), so that subsequent requests will not send it anymore. Example: {% highlight php %} haveHttpHeader('X-Requested-With', 'Codeception'); $I->sendGet('test-headers.php'); // ... $I->deleteHeader('X-Requested-With'); $I->sendPost('some-other-page.php'); {% endhighlight %} #### 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. {% highlight php %} dontSeeBinaryResponseEquals("8c90748342f19b195b9c6b4eff742ded"); {% endhighlight %} 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. {% highlight php %} dontSeeResponseCodeIs(200); // preferred to use \Codeception\Util\HttpCode $I->dontSeeResponseCodeIs(\Codeception\Util\HttpCode::OK); {% endhighlight %} #### 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](#jsonpath) for general info on JSONPath. Opposite to [`seeResponseJsonMatchesJsonPath()`](#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 {% highlight php %} dontSeeXmlResponseMatchesXpath('//root/user[@id=1]'); {% endhighlight %} #### 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](#jsonpath) for general info on JSONPath. Even for a single value an array is returned. Example: {% highlight php %} grabDataFromResponseByJsonPath('$..users[0].id'); $I->sendPut('/user', array('id' => $firstUserId[0], 'name' => 'davert')); {% endhighlight %} #### 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: {% highlight php %} grabResponse(); $I->sendPut('/user', array('id' => $user_id, 'name' => 'davert')); {% endhighlight %} #### 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 [`deleteHeader`](#deleteHeader) to unset it. {% highlight php %} haveHttpHeader('Content-Type', 'application/json'); // all next requests will contain this header {% endhighlight %} #### haveServerParameter * `param ` $name * `param ` $value * `return void` Sets SERVER parameter valid for all next requests. {% highlight php %} $I->haveServerParameter('name', 'value'); {% endhighlight %} #### 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 {% highlight php %} seeBinaryResponseEquals("df589122eac0f6a7bd8795436e692e3675cadc3b"); {% endhighlight %} Example: Using sha1 for a file contents {% highlight php %} seeBinaryResponseEquals(md5($fileData)); {% endhighlight %} Example: Using sha256 hash {% highlight php %} seeBinaryResponseEquals(hash("sha256", base64_decode($fileData)), 'sha256'); {% endhighlight %} #### 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. {% highlight php %} seeHttpHeaderOnce('Cache-Control'); {% endhighlight %} #### seeResponseCodeIs * `part` json * `part` xml * `param int` $code * `return void` Checks response code equals to provided value. {% highlight php %} seeResponseCodeIs(200); // preferred to use \Codeception\Util\HttpCode $I->seeResponseCodeIs(\Codeception\Util\HttpCode::OK); {% endhighlight %} #### 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: {% highlight php %} seeResponseContainsJson(array('name' => 'john')); // response {user: john, profile: { email: john@gmail.com }} $I->seeResponseContainsJson(array('email' => 'john@gmail.com')); {% endhighlight %} 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: {% highlight php %} seeResponseIsValidOnJsonSchemaString('{"type": "object"}'); // response {"name": "john", "age": 20} $schema = [ "properties" => [ "age" => [ "type" => "integer", "minimum" => 18 ] ] ]; $I->seeResponseIsValidOnJsonSchemaString(json_encode($schema)); {% endhighlight %} #### 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](#jsonpath) for general info on JSONPath. Checks if JSON structure in response matches JSONPath. {% highlight 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 } } } {% endhighlight %} {% highlight php %} 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'); {% endhighlight %} #### 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. * {% highlight 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 } } } {% endhighlight %} {% highlight php %} 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'); {% endhighlight %} #### 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. * {% highlight 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 } } } {% endhighlight %} {% highlight php %} 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); {% endhighlight %} #### 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: {% highlight php %} 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]'); {% endhighlight %} 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: {% highlight php %} seeResponseMatchesJsonType([ 'user_id' => 'integer|string', // multiple types 'company' => ['name' => 'string'] ]); {% endhighlight %} 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: * `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: {% highlight php %} 'davert@codeception.com'} $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 ]); {% endhighlight %} You can also add custom filters by using `{@link JsonType::addCustomFilter()}`. See [JsonType reference](https://codeception.com/docs/reference/JsonType). #### 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: {% highlight php %} seeXmlResponseIncludes("1"); {% endhighlight %} #### seeXmlResponseMatchesXpath * `part` xml * `param string` $xPath * `return void` Checks whether XML response matches XPath {% highlight php %} seeXmlResponseMatchesXpath('//root/user[@id=1]'); {% endhighlight %} #### 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. {% highlight php %} sendDelete('/message/1'); {% endhighlight %} #### sendGet * `part` json * `part` xml * `param string` $url * `param array` $params Sends a GET request to given uri. {% highlight php %} sendGet('/users'); // send get with query params $I->sendGet('/orders', ['id' => 1]) {% endhighlight %} #### 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` samva.ua@gmail.com * `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. {% highlight php %} sendPatch('/message/1', ['subject' => 'Read this!']); {% endhighlight %} #### 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: {% highlight php %} sendPost('/message', ['subject' => 'Read this!', 'to' => 'johndoe@example.com']); //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. ``), // 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', ]]); {% endhighlight %} #### sendPut * `part` json * `part` xml * `param string` $url * `param array|string|JsonSerializable` $params * `param array` $files Sends PUT request to given uri. {% highlight php %} sendPut('/message/1', ['subject' => 'Read this!']); {% endhighlight %} #### sendUnlink * `link` https://tools.ietf.org/html/rfc2068#section-19.6.2.4 * `part` json * `part` xml * `author` samva.ua@gmail.com * `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. {% highlight php %} $I->setServerParameters([]); {% endhighlight %} #### startFollowingRedirects * `part` xml * `part` json * `return void` Enables automatic redirects to be followed by the client {% highlight php %} startFollowingRedirects(); {% endhighlight %} #### stopFollowingRedirects * `part` xml * `part` json * `return void` Prevents automatic redirects to be followed by the client {% highlight php %} stopFollowingRedirects(); {% endhighlight %}
Module reference is taken from the source code. Help us to improve documentation. Edit module reference