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.8-SNAPSHOT')

Properties

The properties marked with bold are mandatory.
Property Name Acceptable values Default Description

Configuration of HTTP retries on service unavailability

http.service-unavailable-retry.max-retries

integer

1

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

set of integers

<empty>

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

http.service-unavailable-retry.retry-interval

ISO-8601 duration

PT1S

The retry interval between subsequent requests

http.auth.username

character sequence

<empty>

The username, presence of this property requires the http.auth.password to be also set

http.auth.password

character sequence

<empty>

The password, presence of this property requires the http.auth.username to be also set

http.auth.preemptive-auth-enabled

boolean

false

If enabled the HTTP client will send the basic authentication data even before the service gives an unauthorized response (401), useful when the service doesn’t support unauthorized response (401) or to reduce the overhead of making the connection

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

#{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:

  1. execute sub-steps

  2. wait the polling interval

  3. 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`
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
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
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
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`
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`
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`
Example 13. Save number of id elements
When I set number of elements found by JSON path `$..id` to scenario variable `idsCount`

Save number of elements from JSON

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

When I save number of elements from `$json` found by JSON path `$jsonPath` to $scopes variable `$variableName`
Example 14. Save number of elements from the JSON
When I save number of elements from `[{"key" : "passed"}, {"key" : "failed"}]` found by JSON path `$..[?(@.key == "failed")]` to scenario variable `messageCount`

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

  • passes if the comparison rule matches and the elements number is 0

  • 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 15. 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 16. Verify HTTP resources
Then HTTP resources are valid:
|url                                                    |
|https://saucelabs.com                                  |
|https://vividus-test-site.herokuapp.com/img/vividus.png|