JSONPath Match Assertion

The JSONPath Match assertion uses a JSONPath expression to select content from the target property and compare the result to the value you expect. The assertion passes if they are matching, otherwise it fails.

Important

This assertion applies only to requests and responses, bodies of which contain JSON data.

To learn more about the JSONPath syntax, see JSONPath Reference.

Availability

This assertion is available in multiple ReadyAPI applications. Depending on the application, it validates the following data:

In...	Checks...	To learn more...
Functional tests	The request or response body.	See Working With Assertions in Functional Tests.
Security tests	The response body.	See Security Assertions.
Virtual services	The request body.	See Assertions in Virtual Services.

Create an assertion

Setting up properties

In the JSONPath Expression edit box, specify the JSONPath expression to point at the element you want to compare the result with, or use the toolbar controls to create the expression automatically.
Important
To use the toolbar controls, run the request you want to validate at least once.
Click to call the Select JSON dialog. Use it to select a node from the last request or response and create a JSON path expression for this node.
In the Expected Result edit box, specify the value you are expecting to get. Use the property expansion to point at a specific node.
Use these commands to visually select the value from the existing request or response:
Option
Description
Select Content
Add a property expansion in the result.
Select from Current
Get a value from the last response you have received (or the last request the virtual service has received).
When possible, ReadyAPI converts JSON values to objects of the corresponding type (integer, boolean and so on) and compares them. Otherwise, ReadyAPI treats values as strings.
To command ReadyAPI to compare values as strings, enclose the expected value in quotes. If a string contains quotes, you need to specify a backslash (\) before each of them. For example:
```
"First Name \"Nickname\" Last Name"
```
To command the assertion to use an asterisk wildcard (*) for varying parts of the value, select Allow Wildcards.
Note
If you do not select this option, the assertion will fail on dynamic values.
To test your assertion on the last response you have received (or the last request the virtual service has received), click Test.

Option	Description
Select Content	Add a property expansion in the result.
Select from Current	Get a value from the last response you have received (or the last request the virtual service has received).

Remarks

If the specified JSONPath expression refers to a non-existing JSON node, its value equals an empty string. So, if you leave an empty string in the Expected Result field, the assertion will pass.
It is also possible to specify a property expansion that refers a non-existing property in the Expected Result field. Its value will be an empty string as well. So, if you specify a JSONPath expression that refers to a non-existing node, and a property expansion that refers to a non-existing property as the expected result, the assertion will pass.

Tips

To avoid typing the desired JSONPath expression manually, click and select the desired JSON element or attribute in the subsequent dialog.
ReadyAPI will form the JSONPath expression that refers the selected item and will set the result from the last request or response as the expected result.
ASP.NET-based services enclose the JSON response payload into the d root element for security reasons. By default, ReadyAPI does not strip the d element out, but there is an option to automatically remove it. If you turn this option on, JSON-related assertions created from the JSON response will not take the root element into account, which can cause the assertion to fail unexpectedly.

Notes on Syntax

The assertion ignores the excessive spaces and line breaks within JSON expressions. Use any type of markup you find suitable. For example, the following code:
```
{"test": ["value1", "value2", "value3"], "test2": true}
```
is treated as identical to this one:
```
{
  "test": ["value1", "value2", "value3"],
  "test2": true
}
```
JSONPath expressions can return either a single value or an array, depending on the expression syntax:
- Expression containing filters ([?(filter)] and array slices ([start:end] always returns arrays, even if the resulting array contains a single item. For example:
```
$.section.fields.item[?(@.name=='My Field')].fldValue
```
  – will return an array even if the fldValue element has one value only. To get this value, add an index to the expression:
```
$.section.fields.item[?(@.name=='My Field')].fldValue[0]
```
- Object wildcards will return an array only if the object has 2 or more properties. Otherwise, these will return a value of the single property (this value will keep the initial type). For example, assume that you need to obtain properties of the following object:
```
{
  "section": {
    "first_subsection": {
      "name": "titular"
    },
    "second_subsection": {
      "name": "secondary",
      "contains_images": true
    }
  }
}
```
  The following expression will return a titular string:
```
$.section.first_subsection.*

// The first_subsection element has a single property
```
  The following expression will return an array:
```
$.section.second_subsection.*

// Returns ["name": "secondary", "contains_images": true"]
```
- The behavior of the array wildcards (arr[*]) depends on which ReadyAPI version you use:
  - In ReadyAPI 2.3.0 and later: Array wildcards should always return an array. For the preceding example, the following expression:
    $.section.first_subsection[*]
    – will return an array:
    ["name": "titular"]
  - In ReadyAPI 1.9.0 – 2.2.0: Array wildcards return an array only if the original array includes more than 2 items. For the arrays including a single item, the results vary depending on the item type.
    For example, for the following objects:
    { "section": ["content"], "second_section": [ {"number": 2} ] }
    the JSONPath expressions will work as follows:
    $.section[*] = content // A string $.second_section[*] = [ {"number": 2} ] // An array

Examples

The following JSONPath expression gets all text subelements in the widget element:
```
$.widget.text
```
The following JSONPath expression gets all subelements in the widget element:
```
$.widget.*
```
The following JSONPath expression gets all text subelements of the header type in the widget element:
```
$.widget.text[?(@.type=='header')]
```
The following JSONPath expression gets the element with index 4 from the tags array:
```
$.widget.tags[4]
```
The following JSONPath expression gets the entire tags array:
```
$.widget.tags
```

Other assertions with JSONPath

Add more assertions that use JSONPath expressions:

JSONPath Match Assertion

Important

Availability

Create an assertion

Setting up properties

Important

Note

Remarks

Examples

Other assertions with JSONPath

See Also

Search results