REST steps

This plugin provides a set of steps to interact with a RESTful API.



Install

Include the module in the corresponding section.

es.iti.wakamiti:rest-wakamiti-plugin:2.6.0
<dependency>
  <groupId>es.iti.wakamiti</groupId>
  <artifactId>rest-wakamiti-plugin</artifactId>
  <version>2.6.0</version>
</dependency>

Options

rest.baseURL

  • Type: URL

Defines the base URL for REST calls. This setting is equivalent to the Define base URL step if a more descriptive statement is preferred.

Example:

rest:
  baseURL: https://example.org/api/v2

rest.contentType

  • Type: string
  • Default: JSON

Specifies the type of content to send in the header of REST calls. Accepted values are:

literalcontent-type header value
ANY*/*
TEXTtext/plain
JSONapplication/json, application/javascript, text/javascript, text/json
XMLapplication/xml, text/xml, application/xhtml+xml
HTMLtext/html
URLENCapplication/x-www-form-urlencoded
BINARYapplication/octet-stream
MULTIPARTmultipart/form-data, multipart/alternative, multipart/byteranges, multipart/digest, multipart/mixed, multipart/parallel, multipart/related, multipart/report, multipart/signed, multipart/encrypted

Example:

rest:
  contentType: XML

rest.httpCodeThreshold

  • Type: integer
  • Default: 500

Sets a limit on HTTP response codes. Whenever a REST call returns an HTTP code equal to or greater than this value, the step is automatically marked as failed without checking any other conditions.

Example:

rest:
  httpCodeThreshold: 999

rest.timeout

  • Type: integer
  • Default: 60000

Sets a maximum response time (in milliseconds) for subsequent HTTP requests. If this time is exceeded, the request is aborted and an error is raised.

Example:

rest:
  timeout: 10000

rest.oauth2.url

  • Type: URL required

Specifies the OAuth 2.0 authentication service to use to generate the token to be sent in the Authorization HTTP header of REST calls.

Example:

rest:
  oauth2: 
    url: https://accounts.google.com/o/oauth2/auth

rest.oauth2.clientId

  • Type: string

Sets the clientId parameter for the OAuth 2.0 authentication service defined by the value of the rest.oauth2.url configuration property.

Example:

rest:
  oauth2: 
    clientId: WEB_APP

rest.oauth2.clientSecret

  • Type: string

Sets the clientSecret parameter for the OAuth 2.0 authentication service defined by the value of the rest.oauth2.url configuration property.

Example:

rest:
  oauth2: 
    clientSecret: ABRACADABRAus1ZMGHvq9R

rest.oauth2.cached

  • Type: boolean
  • Default: false

Specifies whether to cache the retrieved token to avoid repeated calls to the oauth service for the same data.

Example:

rest:
  oauth2:
    cached: true

rest.oauth2.parameters

  • Type: property[]

Sets the default parameters for OAuth authentication.

Example:

rest:
  oauth2:
    parameters:
      grant_type: password
      username: pepe
      password: 1234asdf
      scope: something

rest.config.multipart.subtype

  • Type: string
  • Default: form-data

Sets the subtype of multipart HTTP requests. The available values are:

literal
form-data
alternative
byteranges
digest
mixed
parallel
related
report
signed
encrypted

Example:

rest:
  config:
    multipart:
      subtype: mixed

rest.config.multipart.filename

  • Type: string
  • Default: file

Sets the filename of multipart HTTP requests.

Example:

rest:
  config:
    multipart:
      filename: other_name

rest.config.redirect.follow

  • Type: boolean
  • Default: true

Specifies whether to allow redirects in HTTP calls.

Example:

rest:
  config:
    redirect:
      follow: false

rest.config.redirect.allowCircular

  • Type: boolean
  • Default: false

Specifies whether to allow circular redirects in HTTP calls.

Example:

rest:
  config:
    redirect:
      allowCircular: true

rest.config.redirect.rejectRelative

  • Type: boolean
  • Default: false

Specifies whether to reject relative redirects in HTTP calls.

Example:

rest:
  config:
    redirect:
      rejectRelative: true

rest.config.redirect.max

  • Type: integer
  • Default: 100

Sets the maximum number of redirects for HTTP calls.

Example:

rest:
  config:
    redirect:
      max: 150

Steps

Define content type

the REST content type {word}

Declarative-way for setting the configuration property rest.contentType.

Parameters:

NameWakamiti typeDescription
typeword requiredConnection URL

Examples:

Given the REST content type XML

Define base URL

the base URL {url}

Declarative-way for setting the configuration property rest.baseURL.

Parameters:

NameWakamiti typeDescription
urlurl requiredBase URL

Examples:

Given the base URL https://example.org/api

Define service

the REST service {text}

Sets the service path that would be tested. It would be appended to the baseURL.

Parameters:

NameWakamiti typeDescription
servicetext requiredURL segment path

Examples:

Given the REST service '/users`

Define id

Deprecated
* identified by {text}

Sets an entity identifier to be used by the REST service. It would be appended to the baseURL and the service.

Parameters:

NameWakamiti typeDescription
texttext requiredAn entity identifier

Examples:

Given a user identified by 'john'
Given the borrowed book identified by '978-3-16-148410-0'

Define parameters or headers

the (request|query|path|form) parameter {name} with value {value}
the header {name} with value {value}

Sets a header or request, query, path or form parameter. Request parameters will be sent as form data in POST requests, query parameters will be concatenated to the request URL after the path (e.g. /user?param1=abc&param2=123), path parameters will replace the service path fragments indicate with {}, and form parameters will be sent with content-type application/x-www-form-urlencoded.

Parameters:
NameWakamiti typeDescription
nametext requiredHeader or parameter name
valuetext requiredHeader or parameter value
Examples:
Given the request parameter 'age' with value '13'
When the data info is sent to the service
Given the query parameter 'city' with value 'Valencia'
When the user is queried
Given the REST service 'user/{usuario}/items'
And the path parameter 'usuario' with value '25'
Given the form parameter 'age' with value '13'
When the data info is sent to the service
Given the header 'Keep-alive' with value '1200'

Define parameters or headers (table)

the following (request|query|path) parameters:
    {table}
the following headers:
    {table}

Sets multiple headers or request, query, path or form parameters. Request parameters will be sent as form data in POST requests, query parameters will be concatenated to the request URL after the path (e.g. /user?param1=abc&param2=123), path parameters will replace the service path fragments indicate with {}, and form parameters will be sent with content-type application/x-www-form-urlencoded.

Parameters:
NameWakamiti typeDescription
tabletable requiredA table with name and value columns
Examples:
Given the following request parameters:
  | Name | Value    |
  | age  | 13       |
  | city | Valencia |
When the data info is sent to the service
Given the following query parameters:
  | Name | Value    |
  | age  | 13       |
  | city | Valencia |
When the user is queried
Given the service 'user/{user}/items/{item}'
And the following path parameters:
  | Name | Value |
  | user | 25    |
  | item | 7     |
Given the following form parameters:
  | Name | Value    |
  | age  | 13       |
  | city | Valencia |
When the data info is sent to the service
Given the following headers:
  | Name       | Value |
  | Age        | 3600  |
  | Keep-Alive | 1200  |

Define timeout

a timeout of {duration}

Sets a response timeout for the subsequent HTTP requests.

Parameters:
NameWakamiti typeDescription
durationduration requiredThe timeout
Examples:
Given a timeout of 12000 milliseconds
Given a timeout of 2 seconds

Define HTTP code threshold

(that) any request will be successful if its HTTP code {matcher}

Similar to setting the configuration property rest.httpCodeTreshold but using any integer assertion.

Parameters:
NameWakamiti typeDescription
matcherinteger-assertion requiredNumeric comparator
Example:
* any request will be successful if its HTTP code is less than 500

Define basic authentication

the service uses the basic authentication credentials {username}:{password}

Sets the basic authentication credentials to be sent in the Authorization header for the subsequent requests.

Parameters:
NameWakamiti typeDescription
usernametext requiredThe username
passwordtext requiredThe password
Examples:
Given the service uses the basic authentication credentials 'us1532':'xxxxx'

Define oauth2 authentication

the service uses the oauth authentication

Sets the bearer authentication token to be sent in the Authorization header, which is previously retrieved from the configured oauth2 service (url, clientId, clientSecret, parameters), for the following requests.

Examples:
Given the service uses the oauth authentication

Define oauth2 authentication by token

the service uses the oauth authentication token {token}

Sets the bearer authentication token to be sent in the Authorization header for subsequent requests.

Parameters:
NameWakamiti typeDescription
tokentext requiredAuthentication token
Examples:
Given the service uses the oauth authentication token 'hudytw9834y9cqy32t94'

Define oauth2 authentication by token (file)

the service uses the oauth authentication token from the file {file}

Sets the bearer authentication token to be sent in the Authorization header for subsequent requests, from file.

Parameters:
NameWakamiti typeDescription
filefile requiredFile with the authentication token
Examples:
Given the service uses the oauth authentication token from the file 'token.txt'

Define oauth2 authentication by credentials

the service uses the oauth authentication credentials {username}:{password}
the service uses the oauth authentication credentials {username}:{password} with the following parameters:
    {table}

Sets the bearer authentication token to be sent in the Authorization header, which is previously retrieved from the configured oauth2 service (url, clientId, clientSecret), using the indicated credentials, for the following requests.

Additional parameters supported by Oauth can also be added using a table.

Parameters:
NameWakamiti typeDescription
usernametext requiredThe username
passwordtext requiredThe password
tabletableA table with name and value columns
Examples:
Given the service uses the oauth authentication credentials 'us1532':'xxxxx'
Given the service uses the oauth authentication credentials 'us1532':'xxxxx' with the following parameters:
  | name  | value     |
  | scope | something |

Define oauth2 authentication by client

the service uses the oauth authentication
the service uses the oauth authentication with the following parameters:
    {table}

Sets the bearer authentication token to be sent in the Authorization header, which is previously retrieved from the configured oauth2 service (url, clientId, clientSecret), using client data, for the following requests.

Additional parameters supported by Oauth can also be added using a table.

Parameters:
NameWakamiti typeDescription
tabletableA table with name and value columns
Examples:
Given the service uses the oauth authentication
Given the service uses the oauth authentication with the following parameters:
  | name  | value     |
  | scope | something |

Clear authentication

the service does not use authentication

Deletes the authentication header.

Examples:
Given the service does not use authentication

Define multipart subtype

{type} as subtype multipart

Sets the default subtype for multipart requests. This step is equivalent to setting the rest.config.multipart.subtype property. Available values are:

literal
form-data
alternative
byteranges
digest
mixed
parallel
related
report
signed
encrypted

Default value is form-data.

Parameters:
NameWakamiti typeDescription
typetext requiredMultipart subtype
Examples:
Given 'mixed' as subtype multipart

Define multipart filename

{name} as attached file name

Sets the default name for multipart files. This step is equivalent to setting the rest.config.multipart.filename.

Parameters:
NameWakamiti typeDescription
nametext requiredMultipart file name
Examples:
Given 'other_name' as attached file name

Define attached file

the attached file {name} (of type {type}) is included with the following data:
    {data}

Sets a multipart form-data including an attachment from the given in-document content.

Parameters:
NameWakamiti typeDescription
nametext requiredThe control name
typetextThe MimeType of file
datadocument requiredContent to be attached
Examples:
Given the attached file is included with the following data:
  """
  File content
  """

Define attached file (file)

the attached file {name} (of type {type}) is included with the file {file}

Sets a multipart form-data including an attachment from the given in-document content.

Parameters:
NameWakamiti typeDescription
nametext requiredThe control name
typetextThe MimeType of file
filefile requiredFile to be attach
Examples:
Given the attached file 'data/data.txt' is included

Execute GET request

* (is|are) (queried|requested)

Sends a GET request to the previously defined parameters.

Examples:
  Given the service 'users'
And the following query parameters:
| Name | Value |
| user | 25    |
| item | 7     |
When the users are queried
Given the REST service 'users'
And a user identified by '123'
When the user is requested

Execute DELETE request

* (is|are) deleted

Sends a DELETE request to the previously defined endpoint formed with the base URL, the REST service and the entity id.

Examples:
Given the REST service 'users'
And a user identified by '123'
When the user is deleted

Execute PUT request with body

* (is|are) modified with the following data:
    {data}

Sends a PUT request to the previously defined endpoint formed with the base URL, the REST service and the entity id. The payload is provided in-document.

Parameters:
NameWakamiti typeDescription
datadocument requiredThe request payload body
Examples:
Given the REST service 'users'
And a user identified by '123'
When the user is modified with the following data:
  """json
  {
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1980-02-20",
    "address": "221B, Baker Street"
  }
  """

Execute PUT request with body (file)

* (is|are) modified with the data from the file {file}

Sends a PUT request to the previously defined endpoint formed with the base URL, the REST service and the entity id. The payload is provided by the given file.

Parameters:
NameWakamiti typeDescription
filefile requiredA file containing the request payload body
Examples:
Given the REST service 'users'
And a user identified by '123'
When the user is modified with the data from the file 'data/user123.json'

Execute PATCH request

* (is|are) patched

Sends a PATCH request to the previously defined endpoint formed with the base URL, the REST service and the entity id.

Examples:
Given the REST service 'users'
And a user identified by '123'
And the following query parameters:
  | Name | Value    |
  | age  | 13       |
  | city | Valencia |
When the user is patched

Execute PATCH request with body

* (is|are) patched with the following data:
    {data}

Sends a PATCH request to the previously defined endpoint formed with the base URL, the REST service and the entity id. The payload is provided in-document.

Parameters:
NameWakamiti typeDescription
datadocument requiredThe request payload body
Examples:
Given the REST service 'users'
And a user identified by '123'
When the user is patched with the following data:
  """json
  { "firstName": "Jim" }
  """

Execute PATCH request with body (file)

* (is|are) patched with the data from the file {file}

Sends a PATCH request to the previously defined endpoint formed with the base URL, the REST service and the entity id. The payload is provided by the given file.

Parameters:
NameWakamiti typeDescription
filefile requiredA file containing the request payload body
Examples:
Given the REST service 'users'
And a user identified by '123'
When the user is patched with the data from the file 'data/user123.json'

Execute POST request

* (is|are) created
the data info is sent to the service

Sends a POST request to the previously defined endpoint formed with the base URL and the REST service. The payload is empty.

Example:
Given the REST service 'users'
And the following request parameters:
  | nombre | valor    |
  | age    | 13       |
  | city   | Valencia |
When the data info is sent to the service

Execute POST request with body

* (is|are) created with the following data:
    {data}
the following data is sent to the service:
    {data}

Send a POST request to the previously defined endpoint formed with the base URL and the REST service. The payload is provided in-document.

Parameters:
NameWakamiti typeDescription
datadocument requiredRequest payload
Examples:
When the user is created with the following data:
  """json
  {
    "firstName": "John",
    "lastName": "Doe",
    "birthDate": "1980-02-20",
    "address": "221B, Baker Street"
  }
  """
When the following data is sent to the service:
  """json
  { "date": "2021-10-30" }
  """

Execute POST request with body (file)

* (is|are) created with the data from the file {file}
the data from the file {file} is sent to the service

Sends a POST request to the previously defined endpoint formed with the base URL and the REST service. The payload is provided by the given file.

Parameters:
NameWakamiti typeDescription
filefile requiredA file containing the request payload body
Examples:
When the user is created with the data from the file 'data/user123.json'
When the data from the file 'data/booking.json' is sent to the service

Check response HTTP code

the response HTTP code {matcher}

Validate that the HTTP code of the last response satisfies the given assertion.

Parameters:
NameWakamiti typeDescription
matcherinteger-assertion requiredNumber comparator
Examples:
Then the response HTTP code is equal to 201

Check response body

the response is:
    {data}

Validates that the response body is exactly the content of the in-document content.

the response is \(in any order\):
    {data}

Validates that the response body has all the elements specified by the in-document content, but in any order.

the response contains:
    {data}

Validates that the response body contains the given in-document content.

Parameters:
NameWakamiti typeDescription
datadocument requiredThe expected partial content
Examples:
Then the response is:
  """json
  [
    {
      "age": 46,
      "name": "Michael"
    },
    {
      "age": 23,
      "name": "John"
    }
  ]
  """
Then the response is (in any order):
  """json
  [
    {
      "age": 23,
      "name": "John"
    },
    {
      "name": "Michael",
      "age": 46
    }
  ]
  """
Then the response contains:
  """json
  [ { "name": "John" } ]
  """

Check response body (file)

the response is equal to the file {file}

Validates that the response body is exactly the content of the given file.

the response is equal to the file {file} \(in any order\)

Validates that the response body has all the elements provided by the given file, but in any order.

the response contains the file {file}

Validates that the response body contains the content of the given file.

Parameters:
NameWakamiti typeDescription
filefile requiredAn existing file
Examples:
Then the response contains the file 'data/response1.json'

Check response body fragment

the response fragment {fragment} is:
    {data}

Validates that a JSONPath, XPath or GPath response fragment is exactly the content of the in-document content.

the response fragment {fragment} is \(in any order\):
    {data}

Validates that a JSONPath, XPath or GPath response fragment has all the elements specified by the in-document content, but in any order.

the response fragment {fragment} contains:
    {data}

Validates that a JSONPath, XPath or GPath response fragment contains the given in-document content.

Parameters:
NameWakamiti typeDescription
fragmenttextA JSONPath, XPath or GPath query
datadocument requiredThe expected partial content
Examples:
Then the response fragment 'users[1]' is:
  """json
  {
    "age": 23,
    "name": "John"
  }
  """
Then the response fragment 'users[1]' is (in any order):
  """json
  {
    "name": "John",
    "age": 23
  }
  """
Then the response fragment 'users[1]' contains:
  """json
  { "name": "John" }
  """

Check response body fragment (file)

the response is equal to the file {file}

Validates that a JSONPath, XPath or GPath response fragment is exactly the content of the given file.

the response is equal to the file {file} \(in any order\)

Validates that a JSONPath, XPath or GPath response fragment has all the elements specified by the given file, but in any order.

the response contains the file {file}

Validates that a JSONPath, XPath or GPath response fragment contains the given file.

Parameters:
NameWakamiti typeDescription
fragmenttextA JSONPath, XPath or GPath query
filefile requiredAn existing file
Examples:
Then the response fragment 'users[1]' contains the file 'data/response1.json'

Check response body fragment (value)

the (text|integer|decimal) from response fragment {fragment} {matcher}

Validates the value from a JSONPath, XPath or GPath response fragment according a text, integer or decimal assertion.

Parameters:
NameWakamiti typeDescription
fragmenttext requiredA JSONPath, XPath or GPath query
matcher*-assertion requiredComparator
*: text, integer o decimal.
Examples:
Then the decimal from response fragment 'users[1].account.availableMoney' is greater than 23.57
Then the decimal from response fragment 'users[0].lastName' starts with 'J'

Check response content type

the response content type is {word}

Validate that the content type of the last response is the expected. This step would be equivalent to validate the Content-Type response header against the corresponding MIME type.

Parameters:
NameWakamiti typeDescription
wordword requiredANY,TEXT,JSON,XML,HTML,URLENC,BINARY
Examples:
Then the response content type is JSON

Check response size

the response length {matcher}

Validate that the length in bytes of the last response satisfies the given assertion.

Parameters:
NameWakamiti typeDescription
matcherinteger-assertion requiredNumber comparator
Examples:
Then the response length is less than 500

Check response header

the (text|integer|decimal) response header {name} {matcher}

Validate that a header value from the last REST response satisfies the text, integer or decimal assertion.

Parameters:
NameWakamiti typeDescription
nametext requiredThe HTTP header name
matcher*-assertion requiredComparator
*: text, integer o decimal.
Examples:
Then the text response header Content-Encoding contains 'gzip'
Then the integer response header Age is greater than 10

Check response schema

the response satisfies the following schema:
    {data}

Asserts that the response body structure satisfies a given schema. The accepted schema formats are JSON Schema for JSON responses and XML Schema for XML responses (according theContent-Type response header).

Parameters:

nameWakamiti typedescription
datadocument requiredJSON Schema or XML Schema

Examples:

Then the response satisfies the following schema:
  """json
  {
    "$schema": "http://json-schema.org/draft-04/schema#",
    "type": "object",
    "properties": {
      "id":         { "type": "string", "pattern": "[a-zA-Z0-9]+" },
      "name":       { "type": "string" },
      "age":        { "type": "integer", "minimum": 5 },
      "vegetables": {
        "type": "array",
        "items": [ {
          "type": "object",
          "properties": {
            "id":          { "type": "integer" },
            "description": { "type": "string"  }
          },
          "required": [ "id", "description" ]
        } ]
      },
      "contact": {
        "type": "object",
        "properties": {
          "email": { "type": "string", "pattern": "^[a-zA-Z0-9]+@[a-zA-Z0-9\.]+$" }
        }
      }
    }
  }
  """

Check response schema (file)

the response satisfies the schema from the file {file}

Asserts that the response body structure satisfies a schema from a given file. The accepted schema formats are JSON Schema for JSON responses and XML Schema for XML responses (according the Content-Type response header).

Parameters:
nameWakamiti typedescription
filefile requiredJSON Schema or XML Schema file
Examples:
Then the response satisfies the schema from the file 'data/user-schema.json'