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
-
Copy the below line to
dependencies
section of the projectbuild.gradle
fileExample 1. build.gradleimplementation(group: 'org.vividus', name: 'vividus-plugin-rest-api', version: '0.5.6')
-
If the project was imported to the IDE before adding new plugin, re-generate the configuration files for the used IDE and then refresh the project in the used IDE.
Properties
Property Name | Acceptable values | Default | Description |
---|---|---|---|
Configuration of REST API client |
|||
|
|
|
The base request endpoint |
|
|
|
The property family to set HTTP headers for all outgoing requests, e.g. rest-api.http.header.my-sample-header=my-sample-value |
See HTTP configuration for more fine-grained control over the HTTP interactions.
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 |
Dynamic variables
HTTP response as text
The variable provides the HTTP response body of the latest executed HTTP call as string.
${response}
When I send HTTP GET to the relative URL '/get?name=Content'
Then `${response}` matches `.+Home.+`
HTTP response as binary data
The variable provides the HTTP response body of the latest executed HTTP call as binary data.
${response-as-bytes}
When I execute HTTP GET request for resource with URL `https://github.com/vividus-framework/vividus/blob/master/vividus-plugin-excel/src/test/resources/TestTemplate.xlsx?raw=true`
When I create temporary file with name `excel` and content `${response-as-bytes}` and put path to scenario variable `excelPath`
HTTP response code
The variable provides the HTTP response status code of the latest executed HTTP call.
${response-code}
When I send HTTP GET to the relative URL '/get?name=Content'
Then `${response-code}` is equal to `200`
Table Transformers
FROM_JSON
FROM_JSON
transformer constructs a table by mapping table columns to values found by JSON Paths in the source JSON.
Parameter | Description | ||
---|---|---|---|
|
The name of the variable containing source JSON, only variables of scopes |
||
|
The URL of the JSON resource that can be retrieved using the HTTP GET call. |
||
columns |
The semicolon-separated list of mappings between column names and JSON Paths used to get column values. Example 6. Columns parameter format
|
variable and url are competing parameters and only one can be specified at the same time.
|
[
{
"firstName": "Cheryl",
"lastName": "Wilkerson",
"age": 36,
"address": {
"streetAddress": "690 Selah Way",
"city": "Waitsfield",
"postalCode": "05673"
}
},
{
"firstName": "Zachary",
"lastName": "Harrington",
"age": 63,
"address": {
"streetAddress": "4803 Duncan Avenue",
"city": "New York",
"postalCode": "10014"
}
}
]
Given request body: {
"fullName": "<fname> <lname>"
}
When I execute HTTP POST request for resource with URL `https://service-under-test.com/register`
Examples:
{transformer=FROM_JSON, url=https://data-provider/users, columns=fname=$..firstName;lname=$..lastName}
HTTP Steps
Set HTTP request configuration
Set up custom request configuration.
When I set HTTP request configuration:$configItems
-
$configItems
- Table representing list of configuration items with columns "name" and "value" specifying their names and values respectively.Table 3. Available configs Config Acceptable values Request config default value Description expectContinueEnabled
Boolean
false
Whether the 'Expect: 100-Continue' handshake is enabled
staleConnectionCheckEnabled
Boolean
false
Whether stale connection check is to be used
redirectsEnabled
Boolean
true
Whether redirects should be handled automatically
relativeRedirectsAllowed
Boolean
true
Whether relative redirects should be rejected
circularRedirectsAllowed
Boolean
false
Whether "circular redirects" (redirects to the same location) should be allowed
authenticationEnabled
Boolean
true
Whether authentication should be handled automatically
contentCompressionEnabled
Boolean
true
Whether the target server is requested to compress content
normalizeUri
Boolean
true
Whether client should normalize URIs in requests or not
maxRedirects
Integer
50
The maximum number of redirects to be followed
connectionRequestTimeout
Integer
-1
The timeout in milliseconds used when requesting a connection from the connection manager
socketTimeout
Integer
-1
The socket timeout in milliseconds
socketTimeout
Integer
-1
The socket timeout in milliseconds, which is the timeout for waiting for data or, put differently, a maximum period inactivity between two consecutive data packets
cookieSpec
String
null
The name of the cookie specification to be used for HTTP state management
* -1
means "infinity"
http.socket-timeout
set to 15000
When I set HTTP request configuration:
|socketTimeout |
|25000 |
When I execute HTTP GET request for resource with URL `https://vividus-test-site.onrender.com/?pageTimeout=20000`
Then '${responseStatusCode}' is = '200'
Set HTTP request body
Sets HTTP request body that will be used while executing the request. In the case of textual content the default HTTP
request header with name Content-Type
and value text/plain; charset=UTF-8
is set.
No HTTP request header is set in the case of binary content. |
Given request body: $content
-
$content
- HTTP request body.
Given request body: Hello!
Given request body: #{loadBinaryResource(/data/image.png)}
When I set request headers:
|name |value |
|Content-Type|image/png|
When I send HTTP POST to the relative URL '/upload/png'
Prepare multipart HTTP request
Sets multipart request entity that will be used while executing HTTP requests.
Given multipart request:$requestParts
where requestParts
is 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
--
For
FILE
part type - the resource name or the file path. -
For
STRING
orBINARY
part type - the actual content.
-
-
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 I initialize scenario variable `temp-file-content` with value `Your first and last stop for No-Code Test Automation!`
When I create temporary file with name `abc.txt` and content `${temp-file-content}` and put path to scenario variable `temp-file-path`
Given multipart request:
|type |name |value |contentType|fileName |
|file |file-key |/data/file.txt | |anotherName.txt|
|file |file-key2 |${temp-file-path}|text/plain | |
|string|string-key|string1 |text/plain | |
|binary|binary-key|raw |text/plain |raw.txt |
Set form data HTTP request
Sets URL-encoded form data request entity that will be used while executing HTTP requests.
Default HTTP request header with name Content-Type
and value application/x-www-form-urlencoded; charset=UTF-8
is set.
In case if Content-Type
is text/plain
Set HTTP request body should be used
Given form data request:$parameters
-
$parameters
- The ExamplesTable representing list of parameters with columnsname
andvalue
specifying form data request.
Given form data request:
|name |value |
|firstName|Ivan |
|lastName |Ivanov |
|password |!@3qwer|
Add HTTP headers to the request
Adds HTTP headers to the HTTP request.
When I add request headers:$headers
-
headers
- The 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"'
Execute HTTP request with absolute URL
Executes the HTTP request for a resource identified by the absolute URL. The step uses previously set HTTP headers and request body. The HTTP response headers, status code and body can be accessed by the corresponding steps and dynamic variables.
When I execute HTTP $httpMethod request for resource with URL `$url`
-
$httpMethod
- The HTTP method. -
$url
- The URL of the resource on the server.
When I execute HTTP GET request for resource with URL `https://example.com`
Execute HTTP request with relative URL
Executes the HTTP request for a resource identified by the URL relative to the base URL specified by the rest-api.http.endpoint
property. The step uses previously set HTTP headers and request body. The HTTP response headers, status code and body can be
accessed via the corresponding steps and dynamic variables.
When I execute HTTP $httpMethod request for resource with relative URL `$relativeURL`
-
$httpMethod
- The HTTP method. -
$relativeURL
- The relative URL of the resource on the server.
rest-api.http.endpoint=https://httpbin.org
When I execute HTTP GET request for resource with relative URL `/image/jpeg`
Compare HTTP response body against resource
Compares the HTTP response body against the resource data according to the provided rule.
Then response body $validationRule resource at `$resourcePath`
-
$validationRule
- The validation rule, eitheris equal to
oris not equal to
. -
$resourcePath
- The resource path.
When I execute HTTP GET request for resource with URL `https://httpbin.org/image/png`
Then response body is equal to resource at `/images/pig.png`
Validate HTTP response code
Compares the HTTP response status code against the expected number.
Then response code is $comparisonRule `$responseCode`
-
$comparisonRule
- The comparison rule. -
$responseCode
- The expected HTTP response status code.
When I execute HTTP GET request for resource with URL `https://httpbin.org/cfa2fdbc`
Then response code is equal to `404`
Validate HTTP response time
Compares the HTTP response time against the expected number in milliseconds.
Then response time is $comparisonRule `$responseTime` milliseconds
-
$comparisonRule
- The comparison rule. -
$responseTime
- The expected response time in milliseconds.
When I execute HTTP GET request for resource with URL `https://example.com`
Then response time is less than `1000` milliseconds
Valdate number of HTTP response headers
Validates the number of HTTP response headers filtered by the specified name.
Then number of response headers with name `$headerName` is $comparisonRule $number
-
$headerName
- The HTTP response header name. -
$comparisonRule
- The comparison rule. -
$number
- The expected number of headers.
Then number of response headers with name `Strict-Transport-Security` is equal to 1
Validate HTTP response header value
Compares the header value against the expected value according to the comparison rule.
Then value of response header `$headerName` $comparisonRule `$value`
-
$headerName
- The HTTP response header name. -
$comparisonRule
- The string comparison rule. -
$number
- The expected HTTP header value.
When I execute HTTP GET request for resource with URL `https://httpbin.org/robots.txt`
Then value of response header `Content-Type` is equal to `text/plain`
Validate HTTP response header elements
Validates that the response header with the specified name contains elements. Might be useful to verify such HTTP
headers as Set-Cookie
that have values that can be decomposed into multiple elements.
header = [ element ] *( "," [ element ] )
Then response header `$headerName` contains elements:$elements
-
$headerName
- The HTTP response header name. -
$attributes
- The ExamplesTable with expected elements.
When I execute HTTP GET request for resource with URL `https://httpbin.org/authenticate`
Then response header `Set-Cookie` contains elements:
|element |
|JSESSION|
|clientId|
Save HTTP response header value
Saves the HTTP response header value into a variable.
When I save response header `$headerName` value to $scopes variable `$variableName`
-
$headerName
- The HTTP response header name. -
$variableName
- The variable name to store the header value.
When I execute HTTP GET request for resource with URL `https://httpbin.org/brotli`
When I save response header `Content-Length` value to scenario variable `length`
Validate connection security
Validates that the HTTP connection is secured with the defined security protocol.
Then connection is secured using $securityProtocol protocol
-
$securityProtocol
- The expected security protocol, e.g.TLSv1.2
,TLSv1.3
When I execute HTTP GET request for resource with URL `https://httpbin.org/`
Then connection is secured using TLSv1.2 protocol
Wait for JSON element in the HTTP response
Waits for a specified amount of time until HTTP response body contains an element by the specified JSON path. The actions of the step:
-
Execute sub-steps.
-
Check if the HTTP response is present and the response body contains an element by JSON path.
-
If the required JSON element exists or the maximum number of retries is reached, then the execution stops, otherwise the step actions are repeated.
-
Stop step execution if HTTP response is not present or JSON element is found, otherwise sleep for the calculated part of specified duration and repeat actions from the start.
When I wait for presence of element by `$jsonPath` for `$duration` duration retrying $retryTimes times$stepsToExecute
-
$jsonPath
- The JSON path of the element to find. -
$duration
- The time duration to wait in ISO-8601 Durations format. -
$retryTimes
- The maximum of attempts.duration/retryTimes = timeout
is a polling timeout between requests. -
$stepsToExecute
- The sub-steps to execute at each iteration.
When I wait for presence of element by `$.unstableElement` for `PT50S` duration retrying 10 times
|step |
|When I execute HTTP GET request for resource with URL `http://example.com/testing-page` |
Wait for JSON element in the HTTP response with polling interval
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 execute HTTP GET request for resource with 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.onrender.com` supports secure protocols that contain `TLSv1.2,TLSv1.3`
Wait for expected HTTP status code in response
Waits for the specified number of times until HTTP response code is equal to the expected one. In case if the expected code is not returned after all retries, the assertion error will be recorded.
When I wait for response code $responseCode for $duration duration retrying $retryTimes times$stepsToExecute
-
$responseCode
- The expected HTTP status code. -
$duration
- The time duration to wait in ISO-8601 Durations format. -
$retryTimes
- The number of times the request will be retried:duration/retryTimes = timeout
is a polling timeout between requests. -
$stepsToExecute
- The steps to execute at each wait iteration.
When I wait for response code `200` for `PT10S` duration retrying 3 times
|step |
|When I send HTTP GET to the relative URL '/delayed-resource'|
Validate content type of response body
Checks content type of HTTP response body matches to the specified expected content type according to the provided string validation rule.
Then content type of response body $comparisonRule `$contentType`
-
$comparisonRule
- String validation rule. -
$contentType
– Expected content type, e.g.text/html
,application/xml
,application/json
.
application/json
When I execute HTTP GET request for resource with URL `https://httpbin.org/json`
Then content type of response body is equal to `application/json`
Validate absence of response body
Validates that the HTTP response does not contain a body.
Then response does not contain body
When I execute HTTP POST request for resource with URL `https://httpbin.org/json`
Then response does not contain body
Validate size of response body
Compare size of decompressed HTTP response body with the specified expected size in bytes.
Then size of decompressed response body is $comparisonRule `$sizeInBytes`
-
$comparisonRule
- The comparison rule. -
$sizeInBytes
- The expected size of the response body in bytes.
1200
bytesWhen I execute HTTP GET request for resource with URL `https://example.com`
Then size of decompressed response body is greater than or equal to `1200`
Save ZIP archive entries
The step is moved to core package i.e. it’s not required to install any plugin to use this step - it’s available out of the box. |
Validate ZIP archive
The step is moved to core package i.e. it’s not required to install any plugin to use this step - it’s available out of the box. |
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 has already been 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.onrender.com/img/vividus.png|
HTTP cookie steps
Save value of HTTP cookie
Saves cookie to scope variable. If present several cookies with the same name will be saved cookie with the root path value (path is '/').
When I save value of HTTP cookie with name `$cookieName` to $scopes variable `$variableName`
-
$cookieName
- The name of cookie. -
$variableName
- The name of variable.
cookieName
and save its value to scenario variable value
When I execute HTTP GET request for resource with URL `https://httpbin.org/cookies/set/cookieName/cookieValue`
When I save value of HTTP cookie with name `cookieName` to scenario variable `value`
Then '${value}' is equal to 'cookieValue'
Change value of all HTTP cookies
Change cookie value. If several cookies with the same name exist in cookie store, the value will be changed for all of them.
When I change value of all HTTP cookies with name `$cookieName` to `$newCookieValue`
-
$cookieName
- The name of cookie. -
$newCookieValue
- The new value for$cookieName
.
cookieName
and set new value for it newCookieValue
When I execute HTTP GET request for resource with URL `https://httpbin.org/cookies/set/cookieName/cookieValue`
When I change value of all HTTP cookies with name `cookieName` to `newCookieValue`
When I save value of HTTP cookie with name `cookieName` to scenario variable `value`
Then '${value}' is equal to 'newCookieValue'
JSON Steps
Verify context contains data
The step is deprecated and will be removed in VIVIDUS 0.6.0. The replacement is the combination of the dynamic variable and the step validating the JSON element from the input. The replacement pattern is:
|
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
The step is moved to |
Verify number of elements in context
The step is deprecated and will be removed in VIVIDUS 0.6.0. The replacement is the combination of the dynamic variable and the step validating the number of JSON elements from the input. The replacement pattern is:
|
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
The step is moved
to |
Save element from context
The step is deprecated and will be removed in VIVIDUS 0.6.0. The replacement is the combination of the dynamic variable and the step saving JSON element from the input. The replacement pattern is:
|
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
The step is moved to |
Save number of elements in context
The step is deprecated and will be removed in VIVIDUS 0.6.0. The replacement is the combination of the dynamic variable and the step saving the number of JSON elements from the input. The replacement pattern is:
|
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`
Save number of elements from JSON
The step is moved to |
Tips & Tricks
Validate HTTP response body
In order to validate the body of the latest HTTP response use the response dynamic variable to access the body data in conjunction with any step responsible for data validation like data comparison, JSON, XML and other steps.
When I execute HTTP GET request for resource with URL `https://httpbin.org/json`
Then JSON element from `${response}` by JSON path `$.slideshow` is equal to `
{
"author": "Yours Truly",
"date": "date of publication",
"slides": [
{
"title": "Wake up to WonderWidgets!",
"type": "all"
},
{
"items": [
"Why <em>WonderWidgets</em> are great",
"Who <em>buys</em> WonderWidgets"
],
"title": "Overview",
"type": "all"
}
],
"title": "Sample Slide Show"
}
`
Save HTTP response body into variable
The HTTP response body can be saved into static variable by using the init variable step in conjunction with the response dynamic variable, it might be useful if you want to preserve the data for further computations since each subsequent HTTP call rewrites previously received response data.
When I execute HTTP GET request for resource with URL `https://httpbin.org/json`
Given I initialize scenario variable `json` with value `${response}`