Using JSONPath

It is common for mountebank to see JSON documents in his line of business, and he suspects the same may be true for you. With the goal of making JSON easier to work with, mountebank accepts a jsonpath predicate parameter. This parameter narrows the scope of the predicate value to a value matched by the jsonpath selector, much like the except parameter. mountebank suggests avoiding using this parameter on fields that are not JSON documents. He also counsels avoiding the temptation to use it with binary protocols.

mountebank uses the following field with jsonpath:

Field	Required?	Description
`selector`	Yes	The JSONPath selector

You can send the parameter:


{
    "equals": {
        "body": "Catcher in the Rye"
    },
    "jsonpath": {
        "selector": "$..title"
    }
}

The JSONPath parameter follows the same semantics as those obeyed for multi-valued keys described on the main predicates page, like those observed when a querystring has the same key multiple times. Since the JSONPath selector can potentially match multiple nodes in the JSON document, this is an important point to make. deepEquals will require all the values to match (although the order isn't important). All other predicates will match if any node value matches. The examples below explore these semantics.

Examples

Let's create an HTTP imposter with multiple stubs. We'll use redundant predicates simply to demonstrate various ways to use the jsonpath parameter. Where applicable, a comment field is added to the JSON to explain what's going on. Like all superfluous fields, mountebank will ignore it.

POST /imposters HTTP/1.1
Host: localhost:35553
Accept: application/json
Content-Type: application/json

{
    "port": 4545,
    "protocol": "http",
    "stubs": [{
        "responses": [{ "is": { "body": "Basic jsonpath usage" } }],
        "predicates": [
          {
            "equals": { "body": "Catcher in the Rye" },
            "jsonpath": { "selector": "$..title" },
            "caseSensitive": true,
            "comment": "case sensitivity applies to the selector as well as the value"
          },
          {
            "equals": { "body": "RYE" },
            "jsonpath": { "selector": "$..TITLE" },
            "except": "CATCHER IN THE ",
            "comment": "The except regular expression is removed from the value before matching"
          },
          {
            "matches": { "body": "^Catcher" },
            "jsonpath": { "selector": "$..title" }
          },
          {
            "exists": { "body": true },
            "jsonpath": { "selector": "$..title" },
            "comment": "body must exist (e.g. be empty) AND the JSONPath must match at least one node"
          },
          {
            "exists": { "body": false },
            "jsonpath": { "selector": "$..publisher" },
            "comment": "body must not exist (e.g. be empty) OR the JSONPath must not match any nodes"
          }
        ]
    },{
        "responses": [{
            "is": { "body": "JSONPath with attributes and the quirks of deepEquals" }
        }],
        "predicates": [
          {
            "deepEquals": { "body": "Robert Cecil Martin" },
            "jsonpath": { "selector": "$.book[1].author" },
            "comment": "deepEquals expects a string when there is only one match"
          },
          {
            "deepEquals": { "body": ["J. K. Rowling", "Robert Cecil Martin", "Dr. Seuss"] },
            "jsonpath": { "selector": "$.book..author" },
            "comment": "Use an array for deepEquals when there are multiple matches"
          }
        ]
    }]
}

The first predicate uses an jsonpath selector to navigate to all title elements within the JSON within the body field. If body turns out not to be an JSON, none of them will match. The caseSensitive parameter applies both to the predicate value in body and to the selector field in jsonpath. The exists predicate behavior is identical to its behavior with other fields, except now the jsonpath selector must also match if exists is true, or not match if exists is false.

Note that in the example below, there are multiple nodes matching the jsonpath selector. With all predicates except deepEquals, it's sufficient that any of them match.

POST / HTTP/1.1
Host: localhost:4545

{
    "book":[
      {
        "title": "Game of Thrones",
        "isbn:summary": "Dragons and political intrigue",
        "author": "George R.R. Martin"
      },
      {
        "title": "Catcher in the Rye",
        "isbn:summary": "It is a book",
        "author": "J. D. Salinger"
      },
      {
        "title": "Notes from the Underground",
        "isbn:summary": "The world's first existentialist novel",
        "author":"Fyodor Dostoyevsky"
      }
    ]
}

HTTP/1.1 200 OK
Connection: close
Date: Thu, 09 Jan 2014 02:30:31 GMT
Transfer-Encoding: chunked

Basic jsonpath usage

To test the second stub, we'll use deep equals to get a specific title node dependant on what book we are looking at. We can also use deep equals to get all the corresponding nodes.

POST / HTTP/1.1
Host: localhost:4545

{
    "book":[
      {
        "title": "Harry Potter",
        "isbn:summary": "Wizards and Magic",
        "author": "J. K. Rowling"
      },
      {
        "title": "Clean Code",
        "isbn:summary": "Technological bible",
        "author": "Robert Cecil Martin"
      },
      {
        "title": "The Cat in the Hat",
        "isbn:summary": "Childhood classic",
        "author":"Dr. Seuss"
      }
    ]
}

HTTP/1.1 200 OK
Connection: close
Date: Thu, 09 Jan 2014 02:30:31 GMT
Transfer-Encoding: chunked

JSONPath with attributes and the quirks of deepEquals