JSON Plugin

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

Installation

  1. 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.12')
  2. 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`
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`
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`
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`
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`
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`
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`
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
    }
  ])}"
}