JSON Plugin

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

Installation

Copy the below line to dependencies section of the project build.gradle file
Example 1. build.gradle
```
implementation(group: 'org.vividus', name: 'vividus-plugin-json', version: '0.5.11')
```
If the project was imported to the IDE before adding new dependency, re-generate the configuration files for the used IDE and then refresh the project in the used IDE.

Dynamic variables

JSON context

The variable provides the HTTP response body of the latest executed HTTP call by default or the current JSON element for steps iterating over JSON.

${json-context}

Example 2. Validate the HTTP response matches the regular expression

When I send HTTP GET to the relative URL '/get?productsPerPage=5'
Then number of JSON elements from `${json-context}` by JSON path `$.product` is equal to 5

Steps

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

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

Use JsonPath online validator to test your JsonPath.

Save JSON element value 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 value from the input. The replacement pattern is:

When I save JSON element value from `${json-context}` by JSON path `<jsonPath>` to <scopes> variable `<variableName>`

Saves a value of JSON element found in JSON context into the variable with the 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 3. Validate the author of the first book

When I execute HTTP GET request for resource with URL `https://raw.githubusercontent.com/json-path/JsonPath/master/json-path-web-test/src/main/resources/webapp/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

Saves a value of JSON element found in the given JSON into the variable with the 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 4. Validate the title of the second book

When I execute HTTP GET request for resource with URL `https://raw.githubusercontent.com/json-path/JsonPath/master/json-path-web-test/src/main/resources/webapp/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`

Save JSON element

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

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

json - The JSON used to find JSON element.
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.

Example 5. Validate the title of the second book

When I execute HTTP GET request for resource with URL `https://raw.githubusercontent.com/json-path/JsonPath/master/json-path-web-test/src/main/resources/webapp/json/goessner.json`
When I save JSON element 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"`

Save number of JSON elements

Saves the number of elements found in the JSON by JSON path into the variable with the specified name and scope.

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

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

Example 6. 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`

Convert JSON to variable

Converts JSON element into the variable with the 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.

Example 7. Validate the title of the second book

When I convert JSON `{
    "store": {
        "book": [
            {
                "category": "reference",
                "author": "Nigel Rees",
                "title": "Sayings of the Century",
                "price": 8.95
            },
            {
                "category": "fiction",
                "author": "Evelyn Waugh",
                "title": "Sword of Honour",
                "price": 12.99
            }
        ],
    }
}` to scenario variable `jsonData`
Then `${jsonData.store.book[1].title}` is equal to `Sword of Honour`

Convert JSON to variable 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 converting JSON element from the input. The replacement pattern is:

When I convert JSON `${json-context}` to <scopes> variable `<variableName>`

Converts JSON element into the variable with the 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 execute HTTP GET request for resource with URL `https://raw.githubusercontent.com/json-path/JsonPath/master/json-path-web-test/src/main/resources/webapp/json/goessner.json`
When I convert JSON from context to scenario variable `jsonData`
Then `${jsonData.store.book[1].price}` is = `12.99`

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 9. 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}`

Execute steps on JSON elements

Executes steps against all elements found by JSON path in the JSON data. The actions performed by the step are:

searches for elements using JSON path;
checks the elements number matches comparison rule;
passes if the comparison rule matches and the elements number is 0;
otherwise switches JSON context to each found element and executes all steps (no steps will be executed in case of comparison rule mismatch);
restores previous JSON context.

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

Example 10. Alias

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 used to find JSON elements.
jsonPath - The JSON Path used to find JSON elements.
stepsToExecute - The ExamplesTable with a single column containing the steps to execute for each found JSON element.

The context-based step is deprecated and will be removed in VIVIDUS 0.6.0. The dynamic variable must be used instead. The replacement pattern is:

When I find $comparisonRule `<elementsNumber>` JSON elements from `${json-context}` by `<jsonPath>` and for each element do<stepsToExecute>

Example 11. Context-based step

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

Example 12. Alias

When I find $comparisonRule '$elementsNumber' JSON elements by '$jsonPath' and for each element doa$stepsToExecute

comparisonRule - The comparison rule.
elementsNumber - The expected number of elements.
jsonPath - The JSON Path used to find JSON elements.
stepsToExecute - The ExamplesTable with a single column containing the steps to execute for each found JSON element.

Example 13. Validate each accountId consists of digits

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|

Execute steps on JSON elements and exit on condition

Executes steps against all elements found by JSON path in the JSON data until the variable is not set or its value corresponds to the expected one. The actions performed by the step are:

searches for elements using JSON path;
checks the elements number matches comparison rule;
passes if the comparison rule matches and the elements number is 0;
otherwise switches JSON context to each found element and executes all steps until the variable is not set or mismatches the expected value (no steps will be executed in case of comparison rule mismatch);
restores previous JSON context;
fails if the variable has never been set during the iterations execution.

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. 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 used to find JSON elements.
jsonPath - The JSON Path used to find JSON elements.
variableName - The name of the variable to validate.
variableMatcher - The string comparison rule.
expectedValue - The expected value of the variable.
stepsToExecute - The ExamplesTable with a single column containing the steps to execute for each found JSON element.

The context-based step is deprecated and will be removed in VIVIDUS 0.6.0. The dynamic variable must be used instead. The replacement pattern is:

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

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 - The JSON Path used to find JSON elements.
variableName - The name of the variable to validate.
variableMatcher - The string comparison rule.
expectedValue - The expected value of the variable.
stepsToExecute - The ExamplesTable with a single column containing the steps to execute for each found JSON element.

Example 17. Find the title from JSON

When I execute HTTP GET request for resource with URL `https://raw.githubusercontent.com/json-path/JsonPath/master/json-path-web-test/src/main/resources/webapp/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}`

Validate JSON element value 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 validating JSON element value from the input. The replacement pattern is:

Then JSON element value from `${json-context}` by JSON path `<jsonPath` <comparisonRule> `<expectedValue>`

Validates if the JSON context 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 - only single rule IS_EQUAL_TO (readable form: is equal to) is allowed,
- for null - only two rules IS_EQUAL_TO and IS_NOT_EQUAL_TO (readable forms: is equal to and is not equal to) are 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 18. Validate the price of the third book is less than 9

When I execute HTTP GET request for resource with URL `https://raw.githubusercontent.com/json-path/JsonPath/master/json-path-web-test/src/main/resources/webapp/json/goessner.json`
Then JSON element value from context by JSON path `$.store.book[2].price` is less than `9`

Validate JSON element value

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 - only single rule IS_EQUAL_TO (readable form: is equal to) is allowed,
- for null - only two rules IS_EQUAL_TO and IS_NOT_EQUAL_TO (readable forms: is equal to and is not equal to) are 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 19. Validate the price of the fourth book is greater than 22.50

When I execute HTTP GET request for resource with URL `https://raw.githubusercontent.com/json-path/JsonPath/master/json-path-web-test/src/main/resources/webapp/json/goessner.json`
Then JSON element value from `${response}` by JSON path `$.store.book[3].price` is greater than `22.50`

Validate JSON element

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

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

json - The JSON used to find the actual JSON element.
jsonPath - The JSON Path used to find the actual JSON element.
expectedData - The expected JSON element to compare against.
options - The set of JSON comparison options.

Example 20. Validate JSON contains string value by JSON path

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

Validate number of JSON elements

Validates the number of JSON elements found by the JSON path matches the expected number according to the specified comparison rule.

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

json - The JSON used to find the actual JSON elements.
jsonPath - The JSON Path used to find JSON elements.
comparisonRule - The comparison rule.
elementsNumber - The expected number of JSON elements.

Example 21. Validate the number of accounts in JSON is equal to 2

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

Validate JSON against schema

Validates JSON against JSON Schema.

Then JSON `$json` is valid against schema `$schema`

$json - The JSON to validate.
$schema - The JSON Schema.

The step validates JSON according to schema specification version provided in the schema itself, e.g.:

"$schema": "https://json-schema.org/draft/2020-12/schema"

If the version is not present in the schema then JSON is validated according to 2020-12 version.

Example 22. Validate product for sale information

Then JSON `
{
   "productId": 1,
   "productName": "A desk lamp",
   "price": 12.50,
   "tags": [ "lamp", "desk" ]
}
` is valid against schema `
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://example.com/product.schema.json",
  "title": "Product",
  "description": "A product from catalog",
  "type": "object",
  "properties": {
    "productId": {
      "description": "The unique identifier for a product",
      "type": "integer"
    },
    "productName": {
      "type": "string"
    },
    "price": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "tags": {
      "description": "Tags for the product",
      "type": "array",
      "prefixItems": [{
        "type": "string",
        "enum": ["lamp", "desk"]
      }],
      "minItems": 1,
      "uniqueItems": true
    }
  },
  "required": [ "productId", "productName", "price", "tags" ]
}
`

Matchers

Matcher is an object which compares objects against a specific criteria and returns a boolean value indicating whether the match was successful or not.

Embedded matchers, placeholders and expressions can be found on the json-unit library readme.

Array contains any of entries

Validate if actual array contains any of entries from the expected one.

#{json-unit.matches:anyOf}($input)

$input - any string which represents expected array entries

Example 23. Validate entries

Given I initialize story variable `actual-json` with value `
{
  "store":{
    "authors":[
      {
        "name":"Yakub Kolas",
        "available":true
      },
      {
        "name":"Uladzimir Karatkevich",
        "available":true
      }
    ]
  }
}
`
Then JSON element from `${actual-json}` by JSON path `$.store` is equal to `{"book":"#{json-unit.matches:anyOf}[{\"name\":\"Uladzimir Karatkevich\",\"available\":true},{\"author\":\"Yanka Kupala\",\"available\":true}])}"`

As JSON do not support multi line strings if you want to improve readability use escapeJson expression inside matcher

Example 24. Validate entries with escapeJson expression

Then JSON element from `${actual-json}` by JSON path `$.store` is equal to `
{
  "book":"#{json-unit.matches:anyOf}#{escapeJson([
    {
      "name":"Uladzimir Karatkevich",
      "available":true
    },
    {
      "author":"Yanka Kupala",
      "available":true
    }
  ])}"
}