mountebank

mountebank - over the wire test doubles

Fork me on GitHub

the apothecary

Predicates

In the absence of a predicate, a stub always matches, and there's never a reason to add more than one stub to an imposter. Predicates allow imposters to have much richer behavior by defining whether or not a stub matches a request. When multiple stubs are created on an imposter, the first stub that matches is selected.

Each predicate object contains one or more of the request fields as keys. Predicates are added to a stub in an array, and all predicates are AND'd together. The following predicate operators are allowed:

Operator Description
equals The request field matches the predicate
deepEquals Performs nested set equality on the request field, useful when the request field is an object (e.g. the query field in http)
contains The request field contains the predicate
startsWith The request field starts with the predicate
endsWith The request field ends with the predicate
matches The request field matches the JavaScript regular expression defined with the predicate.
exists If true, the request field must exist. If false, the request field must not exist.
not Inverts a predicate
or Logically or's two predicates together
and Logically and's two predicates together
inject Injects JavaScript to decide whether the request matches or not. See the injection page for more details.

Predicates can be parameterized. mountebank accepts the following predicate parameters:

Parameter Default Description
caseSensitive false Determines if the match is case sensitive or not. This includes keys for objects such as query parameters.
except "" Defines a regular expression that is stripped out of the request field before matching.
xpath null Defines an object containing a selector string and, optionally, an ns object field that defines a namespace map.
jsonpath null Defines an object containing a selector string

See the equals example below to see the caseSensitive and except parameters in action. See the xpath page for xpath examples. See the jsonpath page or jsonpath examples.

Almost all predicates are scoped to a request field; see the protocol pages linked to from the sidebar to see the request fields. inject is the sole exception. It takes a string function that accepts the entire request. See the injection page for details.

The predicates work intuitively for base64-encoded binary data as well by internally converting the base64-encoded string to a JSON string representing the byte array. For example, sending "AQIDBA==" will get translated to "[1,2,3,4]", and predicates expecting "AgM=" will get translated to "[2,3]". Even though "AQIDBA==" does not contain "AgM=", a contains predicate will match, because "[1,2,3,4]" does contain "[2,3]". This works well for everything but matches, because any regular expression operators get encoded as binary. mountebank recommends that you stay away from matches if you're dealing in binary. In mountebank's experience, contains is the most useful predicate for binary imposters, as even binary RPC data generally contains strings representing method names.

On occasion you may encounter multi-valued keys. This can be the case with querystrings that have repeating keys, for example ?key=first&key=second. In those cases, deepEquals will require all the values (in any order) to match. All other predicates will match if any value matches, so an equals predicate will match with the value of second in the example above.

Matching XML or JSON

mountebank has special support for matching XML and JSON request fields, such as in an http body or tcp data field. Where XML or JSON predicates are used against string fields, mountebank will attempt to parse the field as XML or JSON and apply the given predicate. If he is unable to parse the field, the predicate will fail; otherwise it will pass or fail according to the selected value.

See the xpath page for xpath examples.

See the json page for json examples.

Examples

The examples below use both HTTP and TCP imposters. The TCP examples use netcat (nc) to send TCP data over a socket, which is like telnet, but makes the output easier to script. The examples for binary imposters use the base64 command line tool to decode base64 to binary before sending to the socket.

Let's create an HTTP imposter with multiple stubs:


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

{
  "port": 4545,
  "protocol": "http",
  "stubs": [
    {
      "responses": [{ "is": { "statusCode": 400 } }],
      "predicates": [
        {
          "equals": {
            "method": "POST",
            "path": "/test",
            "query": {
              "first": "1",
              "second": "2"
            },
            "headers": {
              "Accept": "text/plain"
            }
          }
        },
        {
          "equals": { "body": "hello, world" },
          "caseSensitive": true,
          "except": "!$"
        }
      ]
    },
    {
      "responses": [{ "is": { "statusCode": 406 } }],
      "predicates": [{ "equals": { "headers": { "Accept": "application/xml" } } }]
    },
    {
      "responses": [{ "is": { "statusCode": 405 } }],
      "predicates": [{ "equals": { "method": "PUT" } }]
    },
    {
      "responses": [{ "is": { "statusCode": 500 } }],
      "predicates": [{ "equals": { "method": "PUT" } }]
    }
  ]
}

The first predicate is the most complex, and the request has to match all of the specified request fields. We have the option of putting multiple fields under one equals predicate or splitting each one into a separate predicate in the array. In this example, all of the ones that share the default predicate parameters are together. For those, neither the case of the keys nor the values will affect the outcome. The body predicate is treated separately. The text will be compared in a case-sensitive manner, after stripping away the regular expression !$ (an exclamation mark anchored to the end of the string).

The order of the query parameters and header fields does not matter.


POST /test?Second=2&First=1 HTTP/1.1
Host: localhost:4545
accept: text/plain

hello, world!

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

The second stub matches if the header changes.


POST /test?Second=2&First=1 HTTP/1.1
Host: localhost:4545
Accept: application/xml

"hello, world!"

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

The third stub matches on a PUT.


PUT /test?Second=2&First=1 HTTP/1.1
Host: localhost:4545
Accept: application/json

"hello, world!"

HTTP/1.1 405 Method Not Allowed
Connection: close
Date: Thu, 09 Jan 2014 02:30:31 GMT
Transfer-Encoding: chunked

The fourth stub will never run, since it matches the same requests as the third stub. mountebank always chooses the first stub that matches based on the order you add them to the stubs array when creating the imposter.

Let's create an HTTP imposter with multiple stubs:


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

{
  "port": 4556,
  "protocol": "http",
  "stubs": [
    {
      "responses": [{ "is": { "body": "first" } }],
      "predicates": [{
        "deepEquals": {
          "query": {}
        }
      }]
    },
    {
      "responses": [{ "is": { "body": "second" } }],
      "predicates": [{
        "deepEquals": {
          "query": {
            "first": "1"
          }
        }
      }]
    },
    {
      "responses": [{ "is": { "body": "third" } }],
      "predicates": [{
        "deepEquals": {
          "query": {
            "first": "1",
            "second": "2"
          }
        }
      }]
    }
  ]
}

The first predicate matches only a request without a querystring.


GET /test HTTP/1.1
Host: localhost:4556

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

first

The second stub matches only if the exact querystring is sent.


GET /test?First=1 HTTP/1.1
Host: localhost:4556

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

second

The third stub matches only if both query keys are sent.


GET /test?Second=2&First=1 HTTP/1.1
Host: localhost:4556

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

third

Any additional query parameters will trigger the default HTTP response.


GET /test?Second=2&First=1&Third=3 HTTP/1.1
Host: localhost:4556

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

Let's create a binary TCP imposter with multiple stubs:


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

{
  "port": 4547,
  "protocol": "tcp",
  "mode": "binary",
  "stubs": [
    {
      "responses": [{ "is": { "data": "Zmlyc3QgcmVzcG9uc2U=" } }],
      "predicates": [{ "contains": { "data": "AgM=" } }]
    },
    {
      "responses": [{ "is": { "data": "c2Vjb25kIHJlc3BvbnNl" } }],
      "predicates": [{ "contains": { "data": "Bwg=" } }]
    },
    {
      "responses": [{ "is": { "data": "dGhpcmQgcmVzcG9uc2U=" } }],
      "predicates": [{ "contains": { "data": "Bwg=" } }]
    }
  ]
}

We're sending a base64-encoded version of four bytes: 0x1, 0x2, 0x3, and 0x4. Our first predicate is a base64 encoded version of 0x2 and 0x3. The response is a base64-encoded version of the string "first response":


echo 'AQIDBA==' | base64 --decode | nc localhost 4547

first response

Next we'll send 0x5, 0x6, 0x7, and 0x8, matching on a predicate encoding 0x7 and 0x8:


echo 'BQYHCA==' | base64 --decode | nc localhost 4547

second response

The third stub will never run, since it matches the same requests as the second stub. mountebank always chooses the first stub that matches based on the order you add them to the stubs array when creating the imposter.

Let's create a text-based imposter with multiple stubs. Binary imposters won't see any interesting behavior difference with only startsWith predicates:


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

{
  "port": 4548,
  "protocol": "tcp",
  "mode": "text",
  "stubs": [
    {
      "responses": [{ "is": { "data": "first response" } }],
      "predicates": [{ "startsWith": { "data": "first" } }]
    },
    {
      "responses": [{ "is": { "data": "second response" } }],
      "predicates": [{ "startsWith": { "data": "second" } }]
    },
    {
      "responses": [{ "is": { "data": "third response" } }],
      "predicates": [{ "startsWith": { "data": "second" } }]
    }
  ]
}

The match is not case-sensitive:


echo 'FIRST REQUEST' | nc localhost 4548

first response

The same is true for the second stub.


echo 'Second Request' | nc localhost 4548

second response

The third stub will never run, since it matches the same requests as the second stub. mountebank always chooses the first stub that matches based on the order you add them to the stubs array when creating the imposter.

Let's create a binary-based imposter with multiple stubs:


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

{
  "port": 4549,
  "protocol": "tcp",
  "mode": "binary",
  "stubs": [
    {
      "responses": [{ "is": { "data": "Zmlyc3QgcmVzcG9uc2U=" } }],
      "predicates": [{ "endsWith": { "data": "AwQ=" } }]
    },
    {
      "responses": [{ "is": { "data": "c2Vjb25kIHJlc3BvbnNl" } }],
      "predicates": [{ "endsWith": { "data": "BQY=" } }]
    },
    {
      "responses": [{ "is": { "data": "dGhpcmQgcmVzcG9uc2U=" } }],
      "predicates": [{ "endsWith": { "data": "BQY=" } }]
    }
  ]
}

We'll use the command line base64 tool to decode the request to binary before sending to the imposter. We're sending a base64-encoded version of four bytes: 0x1, 0x2, 0x3, and 0x4. Our first predicate is a base64 encoded version of 0x3 and 0x4. The response is a base64-encoded version of the string "first response":


echo 'AQIDBA==' | base64 --decode | nc localhost 4549

first response

Next we'll send 0x1, 0x2, 0x4, 0x5, and 0x6, matching on a predicate encoding 0x5 and 0x6:


echo 'AQIDBAUG' | base64 --decode | nc localhost 4549

second response

The third stub will never run, since it matches the same requests as the second stub. mountebank always chooses the first stub that matches based on the order you add them to the stubs array when creating the imposter.

Let's create a text-based imposter with multiple stubs. Binary imposters cannot use the matches predicate.


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

{
  "port": 4550,
  "protocol": "tcp",
  "mode": "text",
  "stubs": [
    {
      "responses": [{ "is": { "data": "first response" } }],
      "predicates": [{
        "matches": { "data": "^first\\Wsecond" },
        "caseSensitive": true
      }]
    },
    {
      "responses": [{ "is": { "data": "second response" } }],
      "predicates": [{ "matches": { "data": "second\\s+request" } }]
    },
    {
      "responses": [{ "is": { "data": "third response" } }],
      "predicates": [{ "matches": { "data": "second\\s+request" } }]
    }
  ]
}

The first stub requires a case-sensitive match on a string starting with "first", followed by a non-word character, followed by "second":


echo 'first second' | nc localhost 4550

first response

The second stub is not case-sensitive.


echo 'Second Request' | nc localhost 4550

second response

The third stub will never run, since it matches the same requests as the second stub. mountebank always chooses the first stub that matches based on the order you add them to the stubs array when creating the imposter.

The exists predicate is primarily for object data types, like HTTP headers and query parameters. It works on string fields by simply returning true if the exists value is true and the string if non-empty. Setting the exists value to false inverts the meaning.


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

{
  "port": 4551,
  "protocol": "http",
  "stubs": [
    {
      "responses": [{ "is": { "body": "first response" } }],
      "predicates": [
        {
          "exists": {
            "query": {
              "q": true,
              "search": false
            },
            "headers": {
              "Accept": true,
              "X-Rate-Limit": false
            }
          }
        }
      ]
    },
    {
      "responses": [{ "is": { "body": "second response" } }],
      "predicates": [
        {
          "exists": {
            "method": true,
            "body": false
          }
        }
      ]
    },
    {
      "responses": [{ "is": { "body": "third response" } }],
      "predicates": [
        {
          "exists": { "body": true }
        }
      ]
    }
  ]
}

The first stub matches if the querystring includes q, but not if it includes search, and if the headers include Accept, but not if they include X-Rate-Limit.


GET /?q=mountebank HTTP/1.1
Host: localhost:4551
Accept: text/plain

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

first response

The second stub matches if the request method is a non-empty string (always true), and if the body is empty.


GET / HTTP/1.1
Host: localhost:4551

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

second response

The last stub matches if the body is non-empty:


POST / HTTP/1.1
Host: localhost:4551

non-empty body

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

third response

The not predicate negates its child predicate.


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

{
  "port": 4552,
  "protocol": "tcp",
  "mode": "text",
  "stubs": [
    {
      "responses": [{ "is": { "data": "not test" } }],
      "predicates": [{ "not": { "equals": { "data": "test\n" } } }]
    },
    {
      "responses": [{ "is": { "data": "test" } }],
      "predicates": [{ "equals": { "data": "test\n" } }]
    }
  ]
}

The first stub matches if the is sub-predicate does not match:


echo 'production' | nc localhost 4552

not test

As expected, the second stub matches if the is sub-predicate does match:


echo 'test' | nc localhost 4552

test

The or predicate matches if any of its sub-predicates match.


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

{
  "port": 4553,
  "protocol": "tcp",
  "mode": "text",
  "stubs": [
    {
      "responses": [{ "is": { "data": "matches" } }],
      "predicates": [
        {
          "or": [
            { "startsWith": { "data": "start" } },
            { "endsWith": { "data": "end\n" } },
            { "contains": { "data": "middle" } }
          ]
        }
      ]
    }
  ]
}

The stub matches if the first sub-predicate matches:


echo 'start data transmission' | nc localhost 4553

matches

The stub matches if the second sub-predicate matches:


echo 'data transmission end' | nc localhost 4553

matches

The stub matches if the last sub-predicate matches:


echo 'data middle transmission' | nc localhost 4553

matches

The stub does not match none of the sub-predicates match...


echo 'data transmission' | nc localhost 4553

...which yields an empty response:


The and predicate matches if all of its sub-predicates match.


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

{
  "port": 4554,
  "protocol": "tcp",
  "mode": "text",
  "stubs": [
    {
      "responses": [{ "is": { "data": "matches" } }],
      "predicates": [
        {
          "and": [
            { "startsWith": { "data": "start" } },
            { "endsWith": { "data": "end\n" } },
            { "contains": { "data": "middle" } }
          ]
        }
      ]
    }
  ]
}

The first request matches all sub-predicates, triggering the stub response:


echo 'start middle end' | nc localhost 4554

matches

The stub matches two of the three sub-predicates, which is not enough to match the and predicate.

The stub does not match none of the sub-predicates match...


echo 'start end' | nc localhost 4554

No response is sent.


The inject predicate allows you to inject JavaScript to determine if the predicate should match or not. The JavaScript should be a function that accepts the request object (and optionally a logger) and returns true or false. See the injection page for details.

The execution will have access to a node.js environment. The following example uses node's Buffer object to decode base64 to a byte array.


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

{
  "port": 4555,
  "protocol": "tcp",
  "mode": "binary",
  "stubs": [
    {
      "responses": [{ "is": { "data": "Zmlyc3QgcmVzcG9uc2U=" } }],
      "predicates": [{
        "inject": "function (request, logger) { logger.info('Inside injection'); return new Buffer(request.data, 'base64')[2] > 100; }"
      }]
    },
    {
      "responses": [{ "is": { "data": "c2Vjb25kIHJlc3BvbnNl" } }],
      "predicates": [{
        "inject": "function (request) { return new Buffer(request.data, 'base64')[2] <= 100; }"
      }]
    }
  ]
}

The first stub matches if the third byte is greater than 100. The request we're sending is an encoding [99, 100, 101]:


echo 'Y2Rl' | base64 --decode | nc localhost 4555

first response

The logs will also show the injected log output. The second predicate has to match a request originating from localhost with the third byte less than or equal to 100. We're sending [98, 99, 100]:


echo 'YmNk' | base64 --decode | nc localhost 4555

...giving the response:


second response