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
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 |
---|---|---|---|
Configuration of HTTP retries on service unavailability |
|||
|
|
|
The maximum number of allowed retries if the server responds with a HTTP code from the retry code set defined below |
|
<empty> |
set of integers |
The set of HTTP status codes to be retried. If it’s empty, no retries will be performed |
|
|
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
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})}'
Expression | Result |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 |
---|---|
|
encodes the given URI user info |
|
encodes the given URI host |
|
encodes the given URI path |
|
encodes the given URI path segment |
|
encodes the given URI query |
|
encodes the given URI query parameter |
|
encode the given URI fragment |
Expression | Result |
---|---|
|
user%40vividus.dev:pass |
|
vividus.%D0%B1%D0%B5%D0%BB |
|
/path/with%20spaces/ |
|
path%2Fsegment |
|
a&b=c%20d |
|
a%26b |
|
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 forFILE
part type and the actual content forSTRING
andBINARY
part types -
contentType
- the content type -
fileName
- the name of the file contained in this request part. The parameter is not allowed forSTRING
part type, but it’s required forBINARY
one and optional forFILE
part type
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 columnsname
andvalue
specifying HTTP header
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
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
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
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
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
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
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 -
$variableName
- the variable name
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 -
$variableName
- the variable name
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 -
$variableName
- the variable name
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
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 aspassed
-
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 aspassed
, otherwisefailed
-
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
Then HTTP resources are valid:
|url |
|https://saucelabs.com |
|https://vividus-test-site.herokuapp.com/img/vividus.png|