REST steps

Standard REST steps

Given/And

Syntax

Action

i call <http method> "<url>"

i request <http method> "<url>"

i execute <http method> "<url>"

optional: with parameters:

Will execute the given http method (GET, POST, ...) with the given (optional) parameters

The parameters should be formatted as a table structure of the following form:

| type   | name      | value   |
| <type> | <name>    | <value> |

i call <http method> "<url>"

i request <http method> "<url>"

i execute <http method> "<url>"

with data:

Will execute the given http method with the given data structure

This data structure should be formatted as Yaml

example

    """
        email: username-exists#{id.scenario}@example.org
        password: #{id.scenario}
        firstName: firstName
        lastName: lastName
      """

When/Then/And

Syntax

Action

the response status should be <value>

the response status is <value>

Will check the response status of a REST request against an integer <value>

the response location should be "<value>"

the response location is "<value>"

Will check if the response location of a REST request is equal to a given string

the response should contain "<value>"

the response contains "<value>"

Will check if the response contains a certain key

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

the response should contain "<key>" with value "<value>"

the response contains "<key>" with value "<value>"

Will check if the response contains a certain key with a specific value

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

the response should contain:

the response contains:

Will check if the response contains all keys with corresponding specific values

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

the response should contain <number> entities

the response should contain at least <number> entities

the response should contain at most <number> entities

the response should contain more than <number> entities

the response should contain less than <number> entities

Will check if the number of results in the response matches the given number, depending on the comparison action specified.

Should contain can always be replaced by contains. Entities can also be the singular entity.

response entity "<name>" should contain <number> entities

response entity <number> should contain <number> entities

Will check if the number of child entities of the entity matches the given number. This step supports all comparison actions as the step above.

Should contain can always be replaced by contains. Entities can also be the singular entity.

response entity "<name>" should contain "<key>"

response entity "<name>" contains "<key>"

response entity <number> should contain "<key>"

response entity <number> contains "<key>"

Will check if the named or numbered (1-based) response entity contains a specific key.

This step will fail if the named entity is not present in the response.

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

response entity "<name>" should contain "<key>" with value "<value>"

response entity "<name>" contains "<key>" with value "<value>"

response entity <number> should contain "<key>" with value "<value>"

response entity <number> contains "<key>" with value "<value>"

Will check if the named or numbered (1-based) response entity contains a specific key with a specific value.

This step will fail if the named entity or the specified key is not present in the response.

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

response entity "<name>" should contain:

response entity "<name>" contains:

response entity <number> should contain:

response entity <number> contains:

Will check if the named or numbered (1-based) response entity contains a map of values.

This step will fail if the named entity or complete map is not found in the response.

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

The map of values should be structured as a datastructure as follows:

| <name1>    | <value1> |
| <name2>    | <value2> |

the response should not contain "<value>"

the response does not contain "<value>"

Will check if the response doesn't contain a specific key.

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

the response should not contain "<key>" with value "<value>"

the response does not contain "<key>" with value "<value>"

Will check if the response doesn't contain a specific key with associated value.

This step will not fail if the value of the key is different.

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

the response should not contain:

the response does not contain:

Will check if the response doesn't contain a map with specific keys and associated values.

This step will only fail if at least on of the key-value pairs is found in the response.

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

response entity "<name>" should not contain "<key>"

response entity "<name>" does not contain "<key>"

response entity <number> should not contain "<key>"

response entity <number> does not contain "<key>"

Will check if the named or numbered (1-based) response entity does not a specific key.

This step will fail if the named entity is not present in the response.

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

response entity "<name>" should not contain "<key>" with value "<value>"

response entity "<name>" does not contain "<key>" with value "<value>"

response entity <number> should not contain "<key>" with value "<value>"

response entity <number> does not contain "<key>" with value "<value>"

Will check if the named or numbered (1-based) response entity does not contain a specific key with a specific value.

This step will fail if the named entity is not present in the response, but not if the specified key is not present in the named entity.

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

response entity "<name>" should not contain:

response entity "<name>" does not contain:

response entity <number> should not contain:

response entity <number> does not contain:

Will check if the named or numbered (1-based) response entity does not contain a map of values.

This step will fail if the named entity is not found in the response or one of the key-value pairs of the map is found in the response.

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

The map of values should be structured as a datastructure as follows:

| <name1>    | <value1> |
| <name2>    | <value2> |

the response headers should contain "<key>"

the response headers contain "<key>"

response headers should contain "<key>"

response headers contain "<key>"

Will check if the response headers contain a certain key.

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

the response headers should contain "<key>" with value "<value>"

the response headers contain "<key>" with value "<value>"

response headers should contain "<key>" with value "<value>"

response headers contain "<key>" with value "<value>"

Will check if the response headers contain a certain key and specific value.

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

the response headers should contain:

the response headers contain:

response headers should contain:

response headers contain:

Will check if the response headers contain a certain key and specific value.

This step supports standard Spring Expression language as well as a dot notation and a square bracket notation (more info below)

The map of values should be structured as a datastructure as follows:

| <name1>    | <value1> |
| <name2>    | <value2> |

Authentication

CWB has some built-in support for authenticating rest calls. The variable rest.base.auth can contain an instance of {{com.foreach.cuke.rest.authentication.Authentication}}. This authentication will then be applied to all REST requests. It is also possible to save multiple authentication variables and specify which authentication to use for a particular request.

CWB comes with built-in support for basic and OAuth2 (token) authentication.

Authentication steps

Syntax

Action

(i) create <type> authentication as "<variable_name>" with parameters:

(i) set <type> authentication as "<variable_name>" with parameters:

(i) create <type> authentication as default with parameters:

(i) set <type> authentication as default with parameters:

This will create an authentication of type <type> (basic or oauth) and saves it to a variable on the context.

When using 'defaulf', the variable name is "rest.base.auth".

Authentication examples

Using default basic authentication

# set the authentication instance
* basic authentication as default with parameters:
  | username | demo_client |
  | password | demo        |
# basic authentication will be sent along
* call get "http://somewhere"

Requesting an OAuth2 token and using the response as default authentication

# set an authentication that will request a password grant using the url endpoint
# if url property is not present, "${rest.base.url}/oauth/token" is assumed 
* Given oauth2 authentication as default with parameters:
  | url           | /oauth/token |
  | client_id     | demo_client  |
  | client_secret | demo         |
  | grant_type    | password     |
  | scope         | full         |
  | username      | admin        |
  | password      | admin        |

Manual authentication using an access_token

# retrieve a valid token from somewhere, and set it as OAuth2 bearer authorization
* call get "/api/retrieve-token"
* oauth2 authentication as default with parameters:
  | type         | manual           |
  | access_token | #{response.body} |

Using a specific authentication for a request

Specifying a specific named authentication can be done by adding an auth type parameter on the request.

Scenario: Using a custom basic authentication for a request
  Given basic authentication as "my-authentication" with parameters:
    | username | demo_client |
    | password | demo        |
  When i call get "/webpage" with parameters:
    | type  | name       | value              |
    | auth  | -          | my-authentication  |

Notation support

SpEL

All steps that inspect the response support the Spring Expression Language (SpEL).

Examples of SpEL

* the response entity "['detail']" should contain "['key']" with value "nice"
* the response entity "['detail']['option']" should contain "[0]['optional']" with value "true"
* the response entity 1 should contain:
|  ['option'][0]['optional'] | true |

Dot notation

In SpEL, dots are by default used for properties on objects. However, considering we mostly deal with Maps, we have extended the functionality to support dots for maps as well.

Examples of dot notation

* the response entity "detail" should contain "key" with value "nice"
* the response entity "detail.option" should contain "[0].optional" with value "true"
* the response entity 1 should contain:
|  option[0].optional | true |

Square bracket notation

Normally, if you want to get a member of a list in SpEL, you should use the specific index. We have extended the functionality to support empty square brackets to signify a list. When used, CWB will loop the list in order to find the requested entity.

Examples of square bracket notation

* the response entity "detail[]" should contain "key" with value "nice"
* the response entity "detail.option" should contain "[].optional" with value "true"
* the response entity 1 should contain:
|  option[].optional | true |

File upload

As with the standard file upload in the REST steps, it's possible to post files as byte arrays to a Rest service, with the same notation, but a different keyword.

Note that the content-type 'multipart/form-data' is required, as well as the service under test being configured as a multipart enabled service (for instance, Spring MVC requires a MultipartResolver in order for file uploads to work).

Example of file upload

* i call post "/rest/upload" with parameters:
  | type     | name         | value                                         |
  | header   | content-type | multipart/form-data                           |
  | resource | content      | #{id.scenario}-2.jpeg::/files/test-image.jpeg |
Then the response status should be 200

CSV Support

We support several options for checking CSV responses. This requires the content-type to be set to 'text/csv'. If you do not provide the options, the response parsing will use default values that will work most of the time.

These configuration options should be passed in the request as type 'csv-config'.

name	type	default	alternative option names
with-header	boolean	true	withheader
quote-char	character	\"	quotechar
delimiter	character	,
end-of-line-symbols	string	\r\n	endoflinesymbols, end-of-line, eol-symbols

CSV without headers

When you pass the csv-config option 'with-header' with value 'false', the request will assume that the csv does not contain headers. It will then use a zero-based index as header.

Examples:

Example of csv options

  Scenario Outline: Combine different options
    Given i call get "/rest/csv?withHeader=true&endOfLineSymbols=<eol>&delimiter=<delimiter>&quoteChar=<quoteChar>" with parameters:
      | name         | value       | type       |
      | content-type | text/csv    | header     |
      | end-of-line  | <eol>       | csv-config |
      | delimiter    | <delimiter> | csv-config |
      | quoteChar    | <quoteChar> | csv-config |
    Then the response status should be 200
    And the response entity "csv[1]" should contain "firstName" with value "John"
  Examples:
    | eol  | delimiter | quoteChar |
    | \r\n | ;         | '         |
    | \n   | \|        | #         |

Example of CSV without headers

  Scenario: Support line index for csv without headers
    Given i call get "/rest/csv?withHeader=false" with parameters:
      | name         | value    | type       |
      | content-type | text/csv | header     |
      | with-header  | false    | csv-config |
    Then the response status should be 200
	# csv[0]: check the first row of the response
	# should contain "1": check the value of the second column in the row
    And the response entity "csv[0]" should contain "1" with value "John"
    And the response entity "csv[1]" should contain "1" with value "Bob"