1) JsonPath Match - Verifies the value specified by a JsonPath expression matches some expected value
2) JsonPath Existence Match - Verifies the element specified by a JsonPath expression exists in the target JSON
3) JsonPath Count Match - Verifies the number of matching instances for a given JsonPath expression (if the expression evaluates to an array, the count is the length of the array) equals some expected value
4) JsonPath Regex Match - Similar to the basic JsonPath Match assertion, but the value specified by the JsonPath expression is matched to a regular expression
For those of you unfamiliar with it, JSON stands for JavaScript Object Notation. Like XML, it provides a standardized way to represent complex data across different operating systems, architectures, etc. Here's a typical JSON data block:
{"response":
{
"library":[
{
"title":"War and Peace",
"author":"Tolstoy, Leo",
"pages":1296,
"tags":["literature","Russian","classic"]
},
{
"title":"Harry Potter and the Chamber of Secrets",
"author":"Rowling, J.K.",
"pages":341,
"tags":["fiction","fantasy"]
},
{
"title":"In the Garden of Beasts",
"author":"Larson, Erik",
"pages":448,
"tags":["non-fiction","history"]
}
],
"requestId":12345,
"requestStatus":"OK"
}
}
This JSON defines an object (enclosed in braces in JSON) called response that consists of library, requestId, and requestStatus properties. The library property is an array (enclosed in squared brackets) of objects representing books. Each book object has a title, author, pages, and tags property; the tags property is itself another array of strings.JsonPath is JSON's equivalent of XPath-- it provides a simple way to reference a particular value in JSON. You can read a detailed description of JsonPath at http://goessner.net/articles/JsonPath, but I'll present some quick starting rules here with examples using the JSON data above. JsonPath actually supports two different basic syntaxes, one using bracketed property names to navigate through successive levels of data (e.g., ['parent']['child']), and another using parent.child dot notation syntax similar to what's used in most programming languages. For the sake of brevity, I'll focus on dot notation syntax in this post.
| Description | Example Expression | Example Result |
|---|---|---|
| To get the value of an object's property, separate the property name from the object name (or the portion of the JsonPath expression designating the object) with a dot-- again, if you're familiar with dot notation in programming, it's pretty much the same idea. | response.requestStatus | OK - The response object's requestStatus value |
| Zero-based indexing using brackets indicates a particular element in a JSON array. Note the use of zero-based indexing (i.e., representing the first item with index 0, the second with index 1, etc.) is a key difference from XPath's one-based indexing. | response.library[0].author | Tolstoy, Leo - The author property of the first object in the library array |
| Using * instead of an index number with an array returns all elements in the array. | response.library[*].title | [War and Peace, Harry Potter and the Chamber of Secrets, In the Garden of Beasts] - A JSON array of every title in the library array |
| The JSON data root is designated by $, although this is optional in expressions that explicitly start with the first element of the target JSON data (the examples given above safely omit the $ since they start with the root response element). | $.response.requestStatus | OK - Equivalent to the first example; the requestStatus property of the response object |
| A pair of dots indicates a recursive search for the following property; i.e., the property can be found at any level beneath the property preceding the dots. This is equivalent to double slashes in XPath. | $..requestId | 12345 - The response object's requestId property (note we didn't have to explicitly designate the response object here) |
You can access the length property of an array to determine the index of its last (or some position relative to the last) member. In the example expression, @ represents the last evaluated element-- in this case, the library array-- in the bracketed expression. Remember that because of zero-based indexing, the index of the last member of an array is one less than the array's length, so we subtract 1 from the length to find its index. JsonPath is very particular about brackets and parentheses; the parentheses around the @.length - 1 expression may seem optional, but omitting them will result in an "invalid expression" error. | $..library[(@.length - 1)].author | Larson, Erik - The author property of the last member in the library array. |
| You can also build basic predicate statements within squared brackets to filter on specific criteria. The ? enclosed in brackets indicates a predicate, followed by a test expression in parentheses. Within the predicate expression, the @ character acts as a placeholder for each array member being evaluated by the predicate. So in this example expression we're starting with the result array, then evaluating each member's name property and returning those members where the title property matches 'War and Peace' (note the use of == instead of = to check for equality here). Finally, for each array member that passed the predicate test, we get the value of its pages property. | result.library[?(@.pages > 400)].title | [War and Peace, In the Garden of Beasts] - The title property of every book object with a pages property greater than 400 |
If you'd like to play around with JSON expressions yourself, you can copy and paste the JSON data above into the JsonPath expression tester at http://jsonpath.curiousconcept.com. One thing to keep in mind when working with the JsonPath expression tester: string values returned by JsonPath expressions in SoapUI are not enclosed in quotes, as they are with the JsonPath tester (the examples above show results as they appear in SoapUI).
