REST API Plugin

The plugin provides the following abilities:

build and send HTTP requests
validate HTTP responses (headers, status code, body)
validate JSON content of HTTP response bodies

Installation

Example 1. build.gradle

implementation(group: 'org.vividus', name: 'vividus-plugin-rest-api', version: '0.3.2-SNAPSHOT')

Properties

The properties marked with bold are mandatory.

Property Name Acceptable values Default Description

Property Name	Acceptable values	Default	Description
Configuration of HTTP retries on service unavailability
`http.service-unavailable-retry.max-retries`	`1`	`integer`	The maximum number of allowed retries if the server responds with a HTTP code from the retry code set defined below
`http.service-unavailable-retry.status-codes`	<empty>	set of integers	The set of HTTP status codes to be retried. If it’s empty, no retries will be performed
`http.service-unavailable-retry.retry-interval`	`PT1S`	ISO-8601	The retry interval between subsequent requests

Configuration of HTTP retries on service unavailability

http.service-unavailable-retry.max-retries

1

integer

The maximum number of allowed retries if the server responds with a HTTP code from the retry code set defined below

http.service-unavailable-retry.status-codes

<empty>

set of integers

The set of HTTP status codes to be retried. If it’s empty, no retries will be performed

http.service-unavailable-retry.retry-interval

PT1S

ISO-8601

The retry interval between subsequent requests

Expressions

The expression parameters marked with bold are mandatory.

`removeWrappingDoubleQuotes`

When REST API providing the data in JSON format is used it may be required to extract some values from JSON messages. String values are usually wrapped into double quotes, but sometimes only the value without quotes is needed. This expression allows to remove wrapping double quotes and use the value as is.

#{removeWrappingDoubleQuotes($input)}

$input - any string to remove wrapping double quotes

Example 2. Extracting ID from JSON data and using it in HTTP GET

When I save a JSON element from '${response}' by JSON path '$.id' to story variable 'id'
When I send HTTP GET to the relative URL 'rest/#{removeWrappingDoubleQuotes(${id})}'

Table 1. Examples of the expressions removing wrapping double quotes
Expression	Result
`#{removeWrappingDoubleQuotes("value")}`	`value`
`#{removeWrappingDoubleQuotes(value)}`	`value`
`#{removeWrappingDoubleQuotes()}`	`<empty>`
`#{removeWrappingDoubleQuotes("")}`	`<empty>`
`#{removeWrappingDoubleQuotes(""")}`	`"`
`#{removeWrappingDoubleQuotes("value)}`	`"value`
`#{removeWrappingDoubleQuotes(v"alu"e)}`	`v"alu"e`
`#{removeWrappingDoubleQuotes("va"lu"e")}`	`va"lu"e`
`#{removeWrappingDoubleQuotes("va"lu"e)}`	`"va"lu"e`
`#{removeWrappingDoubleQuotes("va"lue)}`	`"va"lue`
`#{removeWrappingDoubleQuotes(va"lue")}`	`va"lue"`

`encodeUriXyz`

#{encodeUriXyz(..)} is a family of expressions that encode specific URI components (e.g. path, query) by percent encoding illegal characters, which includes non-US-ASCII characters, and also characters that are otherwise illegal within the given URI component type, as defined in RFC 3986.

Syntax Description

Syntax	Description
`#{encodeUriUserInfo($userInfo)}`	encodes the given URI user info
`#{encodeUriHost($host)}`	encodes the given URI host
`#{encodeUriPath($path)}`	encodes the given URI path
`#{encodeUriPathSegment($segment)}`	encodes the given URI path segment
`#{encodeUriQuery($query)}`	encodes the given URI query
`#{encodeUriQueryParameter($queryParameter)}`	encodes the given URI query parameter
`#{encodeUriFragment($fragment)}`	encode the given URI fragment

#{encodeUriUserInfo($userInfo)}

encodes the given URI user info

#{encodeUriHost($host)}

encodes the given URI host

#{encodeUriPath($path)}

encodes the given URI path

#{encodeUriPathSegment($segment)}

encodes the given URI path segment

#{encodeUriQuery($query)}

encodes the given URI query

#{encodeUriQueryParameter($queryParameter)}

encodes the given URI query parameter

#{encodeUriFragment($fragment)}

encode the given URI fragment

Table 2. Examples of the expressions encoding URI parts
Expression	Result
`#{encodeUriUserInfo(user@vividus.dev:pass)}`	user%40vividus.dev:pass
`#{encodeUriHost(vividus.бел)}`	vividus.%D0%B1%D0%B5%D0%BB
`#{encodeUriPath(/path/with spaces/)}`	/path/with%20spaces/
`#{encodeUriPathSegment(path/segment)}`	path%2Fsegment
`#{encodeUriQuery(a&b=c d)}`	a&b=c%20d
`#{encodeUriQueryParameter(a&b)}`	a%26b
`#{encodeUriFragment(frag ment)}`	frag%20ment

HTTP Steps

Init multipart HTTP request

Sets multipart request entity that will be used while executing HTTP requests.

Given multipart request:$requestParts

where requestParts - ExamplesTable representing the list of the request parts with the following columns:

type - one of request part types: STRING, FILE, BINARY
name - the request part name
value - the path to the resource with the content for FILE part type and the actual content for STRING and BINARY part types
contentType - the content type
fileName - the name of the file contained in this request part. The parameter is not allowed for STRING part type, but it’s required for BINARY one and optional for FILE part type

Example 3. Init HTTP request consisting of 4 different parts

Given multipart request:
|type  |name      |value         |contentType|fileName       |
|file  |file-key  |/data/file.txt|           |anotherName.txt|
|file  |file-key2 |/data/file.txt|text/plain |               |
|string|string-key|string1       |text/plain |               |
|binary|binary-key|raw           |text/plain |raw.txt        |

Add HTTP headers to the request

Adds HTTP headers to the HTTP request.

When I add request headers:$headers

headers - ExamplesTable representing the list of the headers with columns name and value specifying HTTP header

Example 4. Add request header with name Accept-Language and value en-ru

When I add request headers:
|name           |value |
|Accept-Language|en-ru |
When I send HTTP GET to the relative URL '/get?name=Content'
Then a JSON element by the JSON path '$.headers.Accept-Language' is equal to '"en-ru"'

Wait for JSON element in the HTTP response

Executes the provided sub-steps until the HTTP response body contains an element by the specified JSON path or the maximum number of retries is reached. The maximum duration of the step execution is not limited. The actions of the step:

execute sub-steps
wait the polling interval
if the required JSON element exists or the maximum number of retries is reached, then the execution stops, otherwise the step actions are repeated

When I wait for presence of element by `$jsonPath` with `$pollingInterval` polling interval retrying $retryTimes times$stepsToExecute

jsonPath - the JSON path of the element to find
pollingInterval - the duration to wait between retries
retryTimes - the maximum number of the retries
stepsToExecute - the sub-steps to execute at each iteration

Example 5. Wait for presence of element by JSON path $.data.testData

When I wait for presence of element by `$.data.testData` with `PT5S` polling interval retrying 10 times
|step                                  |
|When I set request headers:           |
|{headerSeparator=!,valueSeparator=!}  |
|!name          !value                !|
|!Authorization !${accessToken}       !|
|When I issue a HTTP GET request for a resource with the URL '${requestUrl}'|

Validate secure protocols supported by server

Checks that a server defined by the hostname supports secure protocols listed in the protocols parameter.

Then server `$hostname` supports secure protocols that $rule `$protocols`

$hostname - the server hostname
$rule - the collection comparison rule
$protocols - the secure protocols that are expected to match specified $rule

Example 6. Validate the server supports TLSv1.2 and TLSv1.3 protocols

Then server `vividus-test-site.herokuapp.com` supports secure protocols that contain `TLSv1.2,TLSv1.3`

JSON Steps

Verify context contains data

Checks if the JSON context contains an expected data by a JSON path

Then JSON element by JSON path `$jsonPath` is equal to `$expectedData`$options

jsonPath - JSON Path
expectedData - expected JSON
options - options

Example 7. Check JSON context contains JSON object by JSON path

Then JSON element by JSON path `$.accountList[0]` is equal to `
{
  "accountId": 12345,
  "accountName": "${json-unit.any-string}",
  "status": "Active"
}
`ignoring extra fields

Verify JSON contains data

Checks if a JSON contains an expected data by a JSON path

Then JSON element from `$json` by JSON path `$jsonPath` is equal to `$expectedData`$options

json - input JSON
jsonPath - JSON Path
expectedData - expected JSON
options - options

Example 8. Check JSON contains string value by JSON path

Then JSON element from `
{
  "accountId": 12345,
  "status": "Active"
}
` by JSON path `$.status` is equal to `Active`

Verify number of elements in context

Verifies that the number of elements found in the JSON context by a JSON path matches an expected number according to specified comparison rule

Then number of JSON elements by JSON path `$jsonPath` is $comparisonRule $elementsNumber

jsonPath - JSON Path
comparisonRule - comparison rule
elementsNumber - expected elements number

Example 9. Number of account lists in JSON is less than 5

Then number of JSON elements by JSON path `$.accountList` is equal to 2

Verify number of elements in JSON

Verifies that the number of elements found in JSON data by a JSON path matches an expected number according to specified comparison rule

Then number of JSON elements from `$json` by JSON path `$jsonPath` is $comparisonRule $elementsNumber

json - JSON data
jsonPath - JSON Path
comparisonRule - comparison rule
elementsNumber - expected elements number

Example 10. Number of account lists in JSON is equal to 2

Then number of JSON elements from `
[
  {
    "accountId": 843
  },
  {
    "accountId": 233
  }
]
` by JSON path `$..accountId` is equal to 2

Save element from context

Saves value extracted from the JSON context into a variable with specified name

When I save JSON element from context by JSON path `$jsonPath` to $scopes variable `$variableName`

jsonPath - JSON Path
$scopes - the comma-separated set of the variables scopes
$variableName - the variable name

Example 11. Save accountId element from JSON context

When I save JSON element from context by JSON path `$.accountId` to SCENARIO variable `account-id`

Save element from JSON

Saves value extracted from a JSON data into a variable with specified name

When I save JSON element from `$json` by JSON path `$jsonPath` to $scopes variable `$variableName`

json - JSON data
jsonPath - JSON Path
$scopes - the comma-separated set of the variables scopes
$variableName - the variable name

Example 12. Save accountId element from JSON

When I save JSON element from `
{
  "accountId": 12345,
  "status": "Active"
}
` by JSON path `$.accountId` to SCENARIO variable `account-id`

Save number of elements in context

Saves number of elements found in the JSON context by JSON path into a variable

When I set number of elements found by JSON path `$jsonPath` to $scopes variable `$variableName`

jsonPath - JSON Path
$scopes - the comma-separated set of the variables scopes
$variableName - the variable name

Example 13. Save number of id elements

When I set number of elements found by JSON path `$..id` to scenario variable `idsCount`

Perform steps on elements in JSON

Performs steps against all elements found by JSON path in JSON data

Actions performed by step:

searches for elements using JSON path
checks that elements quantity matches comparison rule and elements number
for each element switches JSON context and performs all steps. No steps will be performed in case of comparison rule mismatch
restores previously set context

When I find $comparisonRule `$elementsNumber` JSON elements from `$json` by `$jsonPath` and for each element do$stepsToExecute

comparisonRule - comparison rule
elementsNumber - expected number of elements
json - JSON data
jsonPath - JSON Path
stepsToExecute - steps to perform on JSON elements

Example 14. Verify each account id is a number

When I find > `0` JSON elements from `
{
  "accounts": [
    {
      "accountId": 00,
      "status": "Active"
    },
    {
      "accountId": 01,
      "status": "Active"
    },
    {
      "accountId": 10,
      "status": "Active"
    }
  ]
}
` by `$.accounts.*` and for each element docs
|step                                                                                 |
|Then number of JSON elements by JSON path `$[?(@.accountId =~ /\d+/i)]` is equal to 1|

Validate HTTP resources

Validates the defined HTTP resources

Actions performed by step:

executes HTTP HEAD request against the passed URL
if the status code is 200 then the check is considered as passed
if the status code falls under any of 404, 405, 501, 503 then the HTTP GET request will be sent
if the GET status code is 200 then check is considered as passed, otherwise failed
if the target URL had beed already checked then the check is considered as skipped

Then HTTP resources are valid:$resources

resources - The URLs of HTTP resources to validate

Example 15. Verify HTTP resources

Then HTTP resources are valid:
|url                                                    |
|https://saucelabs.com                                  |
|https://vividus-test-site.herokuapp.com/img/vividus.png|