JSON Plugin

The plugin provides a set of actions for transformation and validation of JSON data.

Installation

Example 1. build.gradle

implementation(group: 'org.vividus', name: 'vividus-plugin-json', version: '0.4.16')

Steps

The steps syntax uses two internal (VIVIDUS-only) terms:

"JSON element" - any part of JSON document including both compex data structures like array, object and primitive values like string in double quotes, number, boolean (true or false) and null.
"JSON element value" or "value of JSON element" - primitive values like string not wrapped into double quotes, number, boolean (true or false) and null.

JSON context is pointed to the latest HTTP response by default.

Save JSON element value from context

Saves a value of JSON element found in JSON context into the variable with specified name and scope.

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

$jsonPath - The JSON Path used to find JSON element value.
$scopes - The comma-separated set of the variables scopes.
$variableName - The name of the variable to save the found JSON element value.

Example 2. Validate the author of the first book

When I issue a HTTP GET request for a resource with the URL 'http://jsonpath.herokuapp.com/json/goessner.json'
When I save JSON element value from context by JSON path `$.store.book[0].author` to scenario variable `author-of-first-book`
Then `${author-of-first-book}` is equal to `Nigel Rees`

Save JSON element value from input

Saves a value of JSON element found in the given JSON into the variable with specified name and scope.

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

$json - The JSON used to find JSON element value.
$jsonPath - The JSON Path used to find JSON element value.
$scopes - The comma-separated set of the variables scopes.
$variableName - The name of the variable to save the found JSON element value.

Example 3. Validate the title of the second book

When I issue a HTTP GET request for a resource with the URL 'http://jsonpath.herokuapp.com/json/goessner.json'
When I save JSON element value from `${response}` by JSON path `$.store.book[1].title` to scenario variable `title-of-second-book`
Then `${title-of-second-book}` is equal to `Sword of Honour`

Validate JSON element value from context

Validates if the JSON contex contains the expected JSON element value matching the comparison rule by the specified JSON path.

Then JSON element value from context by JSON path `$jsonPath` $comparisonRule `$expectedValue`

$jsonPath - The JSON Path used to find JSON element value.
$comparisonRule - The comparison rule to match JSON element value depending on the element type:
- for string - string comparison rules are applicable,
- for number - regular comparison rules are applicable,
- for boolean and null-s - only single rule IS_EQUAL_TO (readable form: is equal to) is allowed
- array and object are complex types and must be validated using another steps dedicated for JSON elements.
$expectedValue - The expected value of JSON element to match according to the comparison rule.

Example 4. Validate the price of the third book is less than 9

When I issue a HTTP GET request for a resource with the URL 'http://jsonpath.herokuapp.com/json/goessner.json'
Then JSON element value from context by JSON path `$.store.book[2].price` is less than `9`

Validate JSON element value from input

Validates if the given JSON contains the expected JSON element value matching the comparison rule by the specified JSON path.

Then JSON element value from `$json` by JSON path `$jsonPath` $comparisonRule `$expectedValue`

$json - The JSON used to find JSON element value.
$jsonPath - The JSON Path used to find JSON element value.
$comparisonRule - The comparison rule to match JSON element value depending on the element type:
- for string - string comparison rules are applicable,
- for number - regular comparison rules are applicable,
- for boolean and null-s - only single rule IS_EQUAL_TO (readable form: is equal to) is allowed
- array and object are complex types and must be validated using another steps dedicated for JSON elements.
$expectedValue - The expected value of JSON element to match according to the comparison rule.

Example 5. Validate the price of the fouth book is greater than 22.50

When I issue a HTTP GET request for a resource with the URL 'http://jsonpath.herokuapp.com/json/goessner.json'
Then JSON element value from `${response}` by JSON path `$.store.book[3].price` is greater than `22.50`

Patch JSON

Modified an input JSON using a sequence of operations defined in JSON patch.

When I patch JSON `$sourceJson` using `$jsonPatch` and save result to $scopes variable `$variableName`

$sourceJson - JSON data to be patched.
$jsonPatch - JSON data with required patch actions according to RFC-6902
$scopes - The comma-separated set of the variables scopes.
$variableName - The name of the variable to save the patched JSON.

Example 6. Patch JSON data

When I patch JSON `{"a":"b"}` using `[{ "op": "replace", "path": "/a", "value": "c" }]` and save result to SCENARIO variable `patchedJson`
Then `{"a":"c"}` is equal to `${patchedJson}`

Convert JSON to variable from input

Converts JSON element into the variable with specified name and scope.

When I convert JSON `$json` to $scopes variable `$variableName`

$json - The JSON used to find JSON element value.
$scopes - The comma-separated set of the variables scopes.
$variableName - The name of the variable to save the found JSON element value.

Example 7. Validate the title of the second book

When I issue a HTTP GET request for a resource with the URL 'http://jsonpath.herokuapp.com/json/goessner.json'
When I convert JSON `${response}` to scenario variable `jsonData`
Then `${jsonData.store.book[1].title}` is equal to `Sword of Honour`

Convert JSON to variable from context

Converts JSON element into the variable with specified name and scope.

When I convert JSON from context to $scopes variable `$variableName`

$scopes - The comma-separated set of the variables scopes.
$variableName - The name of the variable to save the found JSON element value.

Example 8. Validate the price of the second book

When I issue a HTTP GET request for a resource with the URL 'http://jsonpath.herokuapp.com/json/goessner.json'
When I convert JSON from context to scenario variable `jsonData`
Then `${jsonData.store.book[1].price}` is = `12.99`

Perform steps on elements in JSON

Performs steps against all elements found by JSON path in JSON data or the context.

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

Example 9. JSON-based step

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

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

Example 10. Context-based step

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

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

Example 11. Verify each account id is a number from JSON

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 do
|step                                                                                 |
|Then number of JSON elements by JSON path `$[?(@.accountId =~ /\d+/i)]` is equal to 1|

Example 12. Verify each account id is a number from response

When I send HTTP GET to the relative URL 'api/v3/accounts'
When I find > `0` JSON elements from context by `$.accounts.*` and for each element do
|step                                                                                 |
|Then number of JSON elements by JSON path `$[?(@.accountId =~ /\d+/i)]` is equal to 1|

Perform steps on elements in JSON and exit on condition

Performs steps against all elements found by JSON path in JSON data or the context until variable is not set or its value corresponds to the expected one.

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 until variable not set or mismatches expected value. No steps will be performed in case of comparison rule mismatch
Restores previously set context
Step will fail if variable never be set along the iterations

Example 13. JSON-based step

When I find $comparisonRule `$elementsNumber` JSON elements in `$json` by `$jsonPath` and until variable `$variableName` $variableMatcher `$expectedValue` for each element I do:$stepsToExecute

Example 14. JSON-based step alias

When I find $comparisonRule '$elementsNumber' JSON elements in '$json' by '$jsonPath' and until variable '$variableName' $variableMatcher '$expectedValue' for each element I do:$stepsToExecute

comparisonRule - The comparison rule.
elementsNumber - The expected number of elements.
json - The JSON data.
jsonPath - JSON Path.
variableName - The name of variable to validate.
variableMatcher - The string comparison rule.
expectedValue - The expected value of the variable.
stepsToExecute - The steps to perform on JSON elements.

Example 15. Context-based step

When I find $comparisonRule `$elementsNumber` JSON elements in context by `$jsonPath` and until variable `$variableName` $variableMatcher `$expectedValue` for each element I do:$stepsToExecute

Example 16. Context-based step alias

When I find $comparisonRule '$elementsNumber' JSON elements in context by '$jsonPath' and until variable '$variableName' $variableMatcher '$expectedValue' for each element I do:$stepsToExecute

comparisonRule - The comparison rule.
elementsNumber - The expected number of elements.
jsonPath - JSON Path.
variableName - The name of variable to validate.
variableMatcher - The string comparison rule.
expectedValue - The expected value of the variable.
stepsToExecute - The steps to perform on JSON elements.

Example 17. Find the title from JSON

When I execute HTTP GET request for resource with URL `http://jsonpath.herokuapp.com/json/goessner.json`
When I find > `1` JSON elements in `${response}` by `$.store.book` and until variable `title` matches `M.+` for each element I do:
|step|
|When I save JSON element value from context by JSON path `$.title` to scenario variable `title`|
Then `Moby Dick` is = `${title}`

Example 18. Find the title from context

When I execute HTTP GET request for resource with URL `http://jsonpath.herokuapp.com/json/goessner.json`
When I find > `1` JSON elements in context by `$.store.book` and until variable `title` matches `S.+` for each element I do:
|step|
|When I save JSON element value from context by JSON path `$.title` to scenario variable `title`|
Then `Sayings of the Century` is = `${title}`