Testomatio - Test Management for Codeception
If you use Codeception installed using composer, install this module with the following command:
composer require --dev codeception/module-rest
Alternatively, you can enable REST
module in suite configuration file and run
codecept init upgrade4
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.
url
optional - the url of apishortDebugResponse
optional - number of chars to limit the API response lengthmodules:
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 is the equivalent to XPath, for querying JSON data structures. Here’s an Online JSONPath Expressions Tester
Conflicts with SOAP module
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();
@throws ConfigurationException
Adds Bearer authentication via access token.
[Part]
json[Part]
xmlAdds Digest authentication via username/password.
[Part]
json[Part]
xmlAdds HTTP authentication via username/password.
[Part]
json[Part]
xmlAdds 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');
@throws ModuleException
[Part]
json[Part]
xmlDeletes 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->deleteHeader('X-Requested-With');
$I->sendPost('some-other-page.php');
param string
$name the name of the header to delete.[Part]
json[Part]
xmlChecks if the hash of a binary response is not the same as provided.
<?php
$I->dontSeeBinaryResponseEquals("8c90748342f19b195b9c6b4eff742ded");
Opposite to seeBinaryResponseEquals
param string
$hash the hashed data response expectedparam string
$algo the hash algorithm to use. Default md5.[Part]
json[Part]
xmlChecks over the given HTTP header and (optionally) its value, asserting that are not there
param
$value[Part]
json[Part]
xmlChecks 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);
[Part]
json[Part]
xmlChecks whether last response do not contain text.
[Part]
json[Part]
xmlOpposite to seeResponseContainsJson
[Part]
jsonSee #jsonpath for general info on JSONPath.
Opposite to seeResponseJsonMatchesJsonPath()
[Part]
jsonOpposite to seeResponseJsonMatchesXpath
[Part]
jsonOpposite to seeResponseJsonXpathEvaluatesTo
[Part]
jsonOpposite to seeResponseMatchesJsonType
.
[Part]
jsonparam array
$jsonType JsonType structure
@see seeResponseMatchesJsonTypeChecks 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).
param mixed
$xml[Part]
xmlChecks 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).
param mixed
$xml[Part]
xmlChecks whether XML response does not match XPath
<?php
$I->dontSeeXmlResponseMatchesXpath('//root/user[@id=1]');
[Part]
xmlFinds and returns attribute of element. Element is matched by either CSS or XPath
[Part]
xmlSee #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'));
return array
Array of matching items
@throws Exception[Part]
jsonReturns the value of the specified header name
param bool
$first Whether to return the first value or all header valuesreturn string|array The first header value if
$first is true, an array of values otherwise[Part]
json[Part]
xmlReturns 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'));
[Part]
json[Part]
xmlFinds and returns text contents of element. Element is matched by either CSS or XPath
param mixed
$cssOrXPath[Part]
xmlSets a HTTP header to be used for all subsequent requests. Use deleteHeader
to unset it.
<?php
$I->haveHttpHeader('Content-Type', 'application/json');
// all next requests will contain this header
[Part]
json[Part]
xmlSets SERVER parameter valid for all next requests.
$I->haveServerParameter('name', 'value');
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');
param string
$hash the hashed data response expectedparam string
$algo the hash algorithm to use. Default sha1.[Part]
json[Part]
xmlChecks over the given HTTP header and (optionally) its value, asserting that are there
param
$value[Part]
json[Part]
xmlChecks 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');
[Part]
json[Part]
xmlChecks response code equals to provided value.
<?php
$I->seeResponseCodeIs(200);
// preferred to use \Codeception\Util\HttpCode
$I->seeResponseCodeIs(\Codeception\Util\HttpCode::OK);
[Part]
json[Part]
xmlChecks that the response code is 4xx
[Part]
json[Part]
xmlChecks that the response code 3xx
[Part]
json[Part]
xmlChecks that the response code is 5xx
[Part]
json[Part]
xmlChecks that the response code is 2xx
[Part]
json[Part]
xmlChecks whether the last response contains text.
[Part]
json[Part]
xmlChecks 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.
[Part]
jsonChecks if response is exactly the same as provided.
[Part]
json[Part]
xmlChecks whether last response was valid JSON. This is done with json_last_error function.
[Part]
jsonChecks 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
[Part]
json
@see codecept_absolute_path()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));
[Part]
jsonChecks whether last response was valid XML. This is done with libxml_get_last_error function.
[Part]
xmlSee #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');
[Part]
jsonChecks 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');
[Part]
jsonChecks 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);
[Part]
jsonChecks 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:
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:
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-Datesstring: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.
[Part]
json
@see JsonTypeChecks 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).
param mixed
$xml[Part]
xmlChecks 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>");
param mixed
$xml[Part]
xmlChecks whether XML response matches XPath
<?php
$I->seeXmlResponseMatchesXpath('//root/user[@id=1]');
[Part]
xmlSends a HTTP request.
param array|string|JsonSerializable
$params[Part]
json[Part]
xmlSends DELETE request to given uri.
<?php
$I->sendDelete('/message/1');
[Part]
json[Part]
xmlSends a GET request to given uri.
<?php
$response = $I->sendGet('/users');
// send get with query params
$I->sendGet('/orders', ['id' => 1])
[Part]
json[Part]
xmlSends a HEAD request to given uri.
[Part]
json[Part]
xmlSends LINK request to given uri.
param array
$linkEntries (entry is array with keys “uri” and “link-param”)@link https://tools.ietf.org/html/rfc2068#section-19.6.2.4
@author [email protected]
[Part]
json[Part]
xmlSends an OPTIONS request to given uri.
[Part]
json[Part]
xmlSends PATCH request to given uri.
<?php
$response = $I->sendPatch('/message/1', ['subject' => 'Read this!']);
param array|string|JsonSerializable
$params[Part]
json[Part]
xmlSends 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',
]]);
param array|string|JsonSerializable
$paramsparam 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.@see https://php.net/manual/en/features.file-upload.post-method.php @see codecept_data_dir()
[Part]
json[Part]
xmlSends PUT request to given uri.
<?php
$response = $I->sendPut('/message/1', ['subject' => 'Read this!']);
param array|string|JsonSerializable
$params[Part]
json[Part]
xmlSends UNLINK request to given uri.
param array
$linkEntries (entry is array with keys “uri” and “link-param”)
@link https://tools.ietf.org/html/rfc2068#section-19.6.2.4
@author [email protected][Part]
json[Part]
xmlSets SERVER parameters valid for all next requests. this will remove old ones.
$I->setServerParameters([]);
Enables automatic redirects to be followed by the client
<?php
$I->startFollowingRedirects();
[Part]
xml[Part]
jsonPrevents automatic redirects to be followed by the client
<?php
$I->stopFollowingRedirects();
[Part]
xml[Part]
json