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