Using XPath

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

mountebank uses the following fields with xpath:

Field	Required?	Description
`selector`	Yes	The XPath selector
`ns`	No	The XPath namespace map, aliasing a prefix to a URL, which allows you to use the prefix in the `selector`.

You can send the parameter without namespaces...

{
  "equals": { "body": "Harry Potter" },
  "xpath": { "selector": "//title" }
}

...or with namespaces:

{
  "equals": { "body": "Harry Potter" },
  "xpath": {
    "selector": "//a:title"
    "ns": {
      "a": "http://example.com/book"
    }
  }
}

The xpath 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 xpath selector can potentially match multiple nodes in the XML 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 xpath 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:12382
Accept: application/json
Content-Type: application/json

{
  "port": 4545,
  "protocol": "http",
  "stubs": [
    {
      "responses": [{ "is": { "body": "Basic xpath usage" } }],
      "predicates": [
        {
          "equals": { "body": "Harry Potter" },
          "xpath": { "selector": "//title" },
          "caseSensitive": true,
          "comment": "case sensitivity applies to the selector as well as the value"
        },
        {
          "equals": { "body": "POTTER" },
          "xpath": { "selector": "//TITLE" },
          "except": "HARRY ",
          "comment": "The except regular expression is removed from the value before matching"
        },
        {
          "matches": { "body": "^Harry" },
          "xpath": { "selector": "//title" }
        },
        {
          "exists": { "body": true },
          "xpath": { "selector": "//title" },
          "comment": "body must exist (e.g. be empty) AND the xpath must match at least one node"
        },
        {
          "exists": { "body": false },
          "xpath": { "selector": "//title/@first" },
          "comment": "body must not exist (e.g. be empty) OR the xpath must not match any nodes"
        },
        {
          "equals": { "body": 3 },
          "xpath": { "selector": "count(//title)" },
          "comment": "number results from xpath selectors are fine..."
        },
        {
          "equals": { "body": true },
          "xpath": { "selector": "boolean(//title)" },
          "comment": "...as are boolean results"
        }
      ]
    },
    {
      "responses": [{ "is": { "body": "xpath with namespaces" } }],
      "predicates": [
        {
          "contains": { "body": "dragons" },
          "xpath": {
            "selector": "//isbn:summary",
            "ns": {
              "isbn": "http://schemas.isbn.org/ns/1999/basic.dtd"
            }
          }
        },
        {
          "contains": { "body": "dragons" },
          "xpath": {
            "selector": "//*[local-name(.)='summary' and namespace-uri(.)='http://schemas.isbn.org/ns/1999/basic.dtd']"
          },
          "comment": "You can use XPath without namespace aliases if you're so inclined"
        },
        {
          "exists": { "body": false },
          "xpath": { "selector": "//title/@first" },
          "comment": "This lets us test out the third stub without running into a conflict"
        }
      ]
    },
    {
      "responses": [{ "is": { "body": "xpath with attributes and the quirks of deepEquals" } }],
      "predicates": [
        {
          "deepEquals": { "body": "3" },
          "xpath": { "selector": "//books/@count" },
          "comment": "deepEquals expects a string when there is only one match"
        },
        {
          "deepEquals": { "body": ["false", "false", "true"] },
          "xpath": { "selector": "//title/@first" },
          "comment": "Use an array for deepEquals when there are multiple matches (same for a repeating querystring key)"
        }
      ]
    }
  ]
}

The first predicate uses an xpath selector to navigate to all title elements within the XML document within the body field. If body turns out not to be an XML document, none of them will match. The caseSensitive parameter applies both to the predicate value in body and to the selector field in xpath. The exists predicate behavior is identical to its behavior with other fields, except now the xpath 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 xpath selector. With all predicates except deepEquals, it's sufficient that any of them match.

POST / HTTP/1.1
Host: localhost:4545

<books xmlns:isbn="http://schemas.isbn.org/ns/1999/basic.dtd">
  <book>
    <title>Game of Thrones</title>
    <isbn:summary>Dragons and political intrigue</isbn:summary>
  </book>
  <book>
    <title>Harry Potter</title>
    <isbn:summary>Dragons and a boy wizard</isbn:summary>
  </book>
  <book>
    <title>The Hobbit</title>
    <isbn:summary>A dragon and short people</isbn:summary>
  </book>
</books>

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

Basic xpath usage

The XML document above also would match the second stub's predicates, but mountebank always uses the first stub that matches. To test the second stub, we'll namespace the title nodes to get past the first stub.

POST / HTTP/1.1
Host: localhost:4545

<books xmlns:isbn="http://schemas.isbn.org/ns/1999/basic.dtd">
  <book>
    <isbn:title>Game of Thrones</isbn:title>
    <isbn:summary>Dragons and political intrigue</isbn:summary>
  </book>
  <book>
    <isbn:title>Harry Potter</isbn:title>
    <isbn:summary>Dragons and a boy wizard</isbn:summary>
  </book>
  <book>
    <isbn:title>The Hobbit</isbn:title>
    <isbn:summary>A dragon and short people</isbn:summary>
  </book>
</books>

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

xpath with namespaces

The third stub will only match on a first attribute, and expects one to be set to true and two to be set to false. In the interests of providing an unbiased presentation, we'll simply denote which book was first published with this attribute.

POST / HTTP/1.1
Host: localhost:4545

<books count="3" xmlns:isbn="http://schemas.isbn.org/ns/1999/basic.dtd">
  <book>
    <title first="false">Game of Thrones</title>
    <isbn:summary>Dragons and political intrigue</isbn:summary>
  </book>
  <book>
    <title first="false">Harry Potter</title>
    <isbn:summary>Dragons and a boy wizard</isbn:summary>
  </book>
  <book>
    <title first="true">The Hobbit</title>
    <isbn:summary>A dragon and short people</isbn:summary>
  </book>
</books>

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

xpath with attributes and the quirks of deepEquals