@mbtest/mountebank 2.9.2-beta.9050

package/src/views/docs/api/stubs.ejs

@@ -0,0 +1,391 @@
+<%
+title = 'stubs'
+description = 'Creating canned responses using mountebank'
+%>
+
+<%- include('../../_header') -%>
+
+<h1>Stub Responses</h1>
+
+<p>Stubs are a type of test double that return a canned response based on the request.
+mountebank allows you to define a list of stubs when creating an imposter. mountebank
+associates both a list of <em>responses</em> and a list of
+<a href='/docs/api/predicates'><em>predicates</em></a> with each stub.</p>
+
+<p>It doesn't make sense to create an empty array of responses, but each response is under no
+obligation to override the defaults (every protocol defines a default for every response field;
+see the protocol-specific documentation pages linked to from the sidebar for more details).
+The responses array defines a circular buffer - every time the stub is used for the request,
+the first response is pulled from the front of the <code>responses</code> array, evaluated, and pushed
+to the back of the array.  This elegantly does what you want.  In the common case, when you
+always want to return the same response, you just add one response to the array.
+More complex scenarios will require that the same endpoint returns a sequence of
+different responses for the same predicates.  Simply add them all to the array in order.
+When the sequence finishes, it will start over.  More complexity can be added by simply
+adding more responses to the array without complicating the contract.</p>
+
+<h2>Response Types</h2>
+
+<p>Each stub response is defined by a specific response type that defines the behavior of the
+response.  The response types currently supported are:</p>
+
+<table>
+  <tr>
+    <th>Response Type</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>is</code></td>
+    <td>Merges the specified response fields with the response defaults (see the protocol
+      page linked to from the sidebar on the left for the defaults).</td>
+  </tr>
+  <tr>
+    <td><code>proxy</code></td>
+    <td>Proxies the request to the specified destination and returns the response.  The
+    response is saved and can be replayed on subsequent calls.</td>
+  </tr>
+  <tr>
+    <td><code>inject</code></td>
+    <td>Allows you to inject a JavaScript function to create the response object.</td>
+  </tr>
+  <tr>
+    <td><code>fault</code></td>
+    <td>Allows you to specify a connection fault to occur instead of a normal response.</td>
+  </tr>
+</table>
+
+<p>See the <a href='/docs/api/proxies'>proxy</a>, <a href='/docs/api/injection'>
+injection</a> and <a href='/docs/api/faults'>fault</a> pages for detailed examples of those response types, and the
+<a href='/docs/api/predicates'>predicates</a> page for examples of stubs with predicates.
+Multiple stubs only make sense with predicates.</p>
+
+<p>Responses can be parameterized. Right now, only one parameter is supported:</p>
+
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Default</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>repeat</code></td>
+    <td><code>1</code></td>
+    <td>Repeats the response the given number of times.</td>
+  </tr>
+</table>
+
+<p>Stubs can be decorated by adding to the <code>behaviors</code> array.  See the
+<a href='/docs/api/behaviors'>behaviors</a> page for more details.</p>
+
+<h2>Example</h2>
+
+<p>Let's create an http imposter with a couple of <code>is</code> response types.  It will simulate
+a RESTful endpoint that creates a customer the first time it's called and returns a 400
+the second time it's called because the email already exists.  We add a second stub that returns a
+404 on any request that isn't a <code>POST</code> to <code>/customers/123</code></p>
+
+<testScenario name='example'>
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json
+Content-Type: application/json
+
+{
+  "port": 4545,
+  "protocol": "http",
+  "recordRequests": true,
+  "stubs": [
+    {
+      "predicates": [
+        {
+          "equals": {
+            "method": "POST",
+            "path": "/customers/123"
+          }
+        }
+      ],
+      "responses": [
+        {
+          "is": {
+            "statusCode": 201,
+            "headers": {
+              "Location": "http://localhost:4545/customers/123",
+              "Content-Type": "application/xml"
+            },
+            "body": "&lt;customer&gt;&lt;email&gt;customer@test.com&lt;/email&gt;&lt;/customer&gt;"
+          }
+        },
+        {
+          "is": {
+            "statusCode": 400,
+            "headers": {
+              "Content-Type": "application/xml"
+            },
+            "body": "&lt;error&gt;email already exists&lt;/error&gt;"
+          }
+        }
+      ]
+    },
+    {
+      "responses": [
+        {
+          "is": { "statusCode": 404 }
+        }
+      ]
+    }
+  ]
+}</code></pre>
+    </step>
+
+<p>Let's assume the application under test makes the initial call...</p>
+
+    <step type='http'>
+<pre><code>POST /customers/123 HTTP/1.1
+Host: localhost:4545
+Accept: application/xml
+Content-Type: application/xml
+
+&lt;customer&gt;
+  &lt;email&gt;customer@test.com&lt;/email&gt;
+&lt;/customer&gt;</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 201 Created
+Location: http://localhost:4545/customers/123
+Content-Type: application/xml
+Connection: close
+Date: <volatile>Thu, 09 Jan 2014 02:30:31 GMT</volatile>
+Transfer-Encoding: chunked
+
+&lt;customer&gt;&lt;email&gt;customer@test.com&lt;/email&gt;&lt;/customer&gt;</code></pre>
+        </assertResponse>
+    </step>
+
+<p>...and the second call:</p>
+
+    <step type='http'>
+<pre><code>POST /customers/123 HTTP/1.1
+Host: localhost:4545
+Accept: application/xml
+Content-Type: application/xml
+
+&lt;customer&gt;
+  &lt;email&gt;customer@test.com&lt;/email&gt;
+&lt;/customer&gt;</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 400 Bad Request
+Content-Type: application/xml
+Connection: close
+Date: <volatile>Thu, 09 Jan 2014 02:30:31 GMT</volatile>
+Transfer-Encoding: chunked
+
+&lt;error&gt;email already exists&lt;/error&gt;</code></pre>
+        </assertResponse>
+    </step>
+
+<p>Now let's see the <code>requests</code> that mountebank
+has saved for you:</p>
+
+    <step type='http'>
+<pre><code>GET /imposters/4545 HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 200 OK
+Vary: Accept
+Content-Type: application/json; charset=utf-8
+Content-Length: <volatile>4212</volatile>
+Date: <volatile>Thu, 09 Jan 2014 02:30:31 GMT</volatile>
+Connection: keep-alive
+
+{
+  "protocol": "http",
+  "port": 4545,
+  "numberOfRequests": 2,
+  "recordRequests": true,
+  "requests": [
+    {
+      "requestFrom": "<volatile>::ffff:127.0.0.1:60523</volatile>",
+      "method": "POST",
+      "path": "/customers/123",
+      "query": {},
+      "headers": {
+        "Host": "localhost:4545",
+        "Accept": "application/xml",
+        "Content-Type": "application/xml",
+        "Connection": "keep-alive",
+        "Transfer-Encoding": "chunked"
+      },
+      "body": "&lt;customer&gt;\n  &lt;email&gt;customer@test.com&lt;/email&gt;\n&lt;/customer&gt;",
+      "ip": "<volatile>::ffff:127.0.0.1</volatile>",
+      "timestamp": "<volatile>2014-01-09T02:30:31.022Z</volatile>"
+    },
+    {
+      "requestFrom": "<volatile>::ffff:127.0.0.1:60523</volatile>",
+      "method": "POST",
+      "path": "/customers/123",
+      "query": {},
+      "headers": {
+        "Host": "localhost:4545",
+        "Accept": "application/xml",
+        "Content-Type": "application/xml",
+        "Connection": "keep-alive",
+        "Transfer-Encoding": "chunked"
+      },
+      "body": "&lt;customer&gt;\n  &lt;email&gt;customer@test.com&lt;/email&gt;\n&lt;/customer&gt;",
+      "ip": "<volatile>::ffff:127.0.0.1</volatile>",
+      "timestamp": "<volatile>2014-01-09T02:30:31.043Z</volatile>"
+    }
+  ],
+  "stubs": [
+    {
+      "predicates": [
+        {
+          "equals": {
+            "method": "POST",
+            "path": "/customers/123"
+          }
+        }
+      ],
+      "responses": [
+        {
+          "is": {
+            "statusCode": 201,
+            "headers": {
+              "Location": "http://localhost:4545/customers/123",
+              "Content-Type": "application/xml"
+            },
+            "body": "&lt;customer&gt;&lt;email&gt;customer@test.com&lt;/email&gt;&lt;/customer&gt;"
+          }
+        },
+        {
+          "is": {
+            "statusCode": 400,
+            "headers": {
+              "Content-Type": "application/xml"
+            },
+            "body": "&lt;error&gt;email already exists&lt;/error&gt;"
+          }
+        }
+      ],
+      "_links": {
+        "self": { "href": "http://localhost:<%= port %>/imposters/4545/stubs/0" }
+      }
+    },
+    {
+      "responses": [
+        {
+          "is": { "statusCode": 404 }
+        }
+      ],
+      "_links": {
+        "self": { "href": "http://localhost:<%= port %>/imposters/4545/stubs/1" }
+      }
+    }
+  ],
+  "_links": {
+    "self": { "href": "http://localhost:<%= port %>/imposters/4545" },
+    "stubs": { "href": "http://localhost:<%= port %>/imposters/4545/stubs" }
+  }
+}</code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+
+<code class='hidden'>DELETE /imposters/4545 HTTP/1.1
+Host: localhost:<%= port %></code>
+    </step>
+</testScenario>
+
+<h2>Repeat example</h2>
+
+<p>The <code>repeat</code> behavior allows certain responses to return a certain number of times before
+    moving on to the next response in the array. In the below example, the first response is configured to
+    return 2 times before advancing to the second response:</p>
+
+<testScenario name='repeat'>
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json
+Content-Type: application/json
+
+{
+  "port": 7777,
+  "protocol": "http",
+  "stubs": [
+    {
+      "responses": [
+        {
+          "is": {
+            "body": "This will repeat 2 times"
+          },
+          "repeat": 2
+        },
+        {
+          "is": {
+            "body": "Then this will return"
+          }
+        }
+      ]
+    }
+  ]
+}</code></pre>
+    </step>
+
+<p>Now the first response will return 2 times before returning the second response.</p>
+
+    <step type='http'>
+<pre><code>GET / HTTP/1.1
+Host: localhost:7777</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 200 OK
+Connection: close
+Date: <volatile>Thu, 01 Jan 2015 02:30:31 GMT</volatile>
+Transfer-Encoding: chunked
+
+This will repeat 2 times</code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<pre><code>GET / HTTP/1.1
+Host: localhost:7777</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 200 OK
+Connection: close
+Date: <volatile>Thu, 01 Jan 2015 02:30:31 GMT</volatile>
+Transfer-Encoding: chunked
+
+This will repeat 2 times</code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<pre><code>GET / HTTP/1.1
+Host: localhost:7777</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 200 OK
+Connection: close
+Date: <volatile>Thu, 01 Jan 2015 02:30:31 GMT</volatile>
+Transfer-Encoding: chunked
+
+Then this will return</code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/7777 HTTP/1.1
+Host: localhost:<%= port %></code>
+    </step>
+</testScenario>
+
+
+<%- include('../../_footer') -%>

package/src/views/docs/api/xpath.ejs

@@ -0,0 +1,281 @@
+<%
+title = 'xpath'
+description = 'Using XPath in mountebank predicates'
+%>
+
+<%- include('../../_header') -%>
+
+<h1>Using XPath</h1>
+
+<p>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 <code>xpath</code> predicate parameter.  This parameter narrows the scope of the predicate
+value to a value matched by the xpath selector, much like the <a href='/docs/api/predicates'>
+<code>except</code> parameter</a>.  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.</p>
+
+<p>mountebank uses the following fields with xpath:</p>
+
+<table>
+  <tr>
+    <th>Field</th>
+    <th>Required?</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>selector</code></td>
+    <td>Yes</td>
+    <td>The XPath selector</td>
+  </tr>
+  <tr>
+    <td><code>ns</code></td>
+    <td>No</td>
+    <td>The XPath namespace map, aliasing a prefix to a URL, which allows you to use the prefix in
+    the <code>selector</code>.</td>
+  </tr>
+</table>
+
+<p>You can send the parameter without namespaces...</p>
+
+<pre><code>{
+  "equals": { "body": "Harry Potter" },
+  "xpath": { "selector": "//title" }
+}</code></pre>
+
+<p>...or with namespaces:</p>
+
+<pre><code>{
+  "equals": { "body": "Harry Potter" },
+  "xpath": {
+    "selector": "//a:title"
+    "ns": {
+      "a": "http://example.com/book"
+    }
+  }
+}</code></pre>
+
+<p>The xpath parameter follows the same semantics as those obeyed for multi-valued keys described on the
+<a href='/docs/api/predicates'>main predicates page</a>, 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.  <code>deepEquals</code> 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.</p>
+
+<h2>Examples</h2>
+
+<p>Let's create an HTTP imposter with multiple stubs.  We'll use redundant predicates simply to
+demonstrate various ways to use the <code>xpath</code> parameter.  Where applicable, a
+<code>comment</code> field is added to the JSON to explain what's going on.  Like all superfluous
+fields, mountebank will ignore it.</p>
+
+<testScenario name='xpath'>
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json
+Content-Type: application/json
+
+{
+  "port": 4545,
+  "protocol": "http",
+  "stubs": [<strong class='highlight1'>
+    {
+      "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"
+        }
+      ]
+    }</strong>,<strong class='highlight2'>
+    {
+      "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"
+        }
+      ]
+    }</strong>,<strong class='highlight3'>
+    {
+      "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)"
+        }
+      ]
+    }</strong>
+  ]
+}</code></pre>
+    </step>
+
+<p>The first predicate uses an xpath selector to navigate to all <code>title</code> elements
+within the XML document within the <code>body</code> field.  If <code>body</code> turns out not
+to be an XML document, none of them will match.  The <code>caseSensitive</code> parameter applies
+both to the predicate value in <code>body</code> and to the <code>selector</code> field in
+<code>xpath</code>.  The <code>exists</code> predicate behavior is identical to its behavior with
+other fields, except now the xpath selector must also match if <code>exists</code> is <code>true</code>,
+or not match if <code>exists</code> is false.<p>
+
+<p>Note that in the example below, there are multiple nodes matching the xpath selector.  With all
+predicates except <code>deepEquals</code>, it's sufficient that <i>any</i> of them match.</p>
+
+    <step type='http'>
+<pre><code>POST / HTTP/1.1
+Host: localhost:4545
+
+&lt;books xmlns:isbn=&quot;http://schemas.isbn.org/ns/1999/basic.dtd&quot;&gt;
+  &lt;book&gt;
+    &lt;title&gt;Game of Thrones&lt;/title&gt;
+    &lt;isbn:summary&gt;Dragons and political intrigue&lt;/isbn:summary&gt;
+  &lt;/book&gt;
+  &lt;book&gt;
+    <strong class='highlight1'>&lt;title&gt;Harry Potter&lt;/title&gt;</strong>
+    &lt;isbn:summary&gt;Dragons and a boy wizard&lt;/isbn:summary&gt;
+  &lt;/book&gt;
+  &lt;book&gt;
+    &lt;title&gt;The Hobbit&lt;/title&gt;
+    &lt;isbn:summary&gt;A dragon and short people&lt;/isbn:summary&gt;
+  &lt;/book&gt;
+&lt;/books&gt;</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 200 OK
+Connection: close
+Date: <volatile>Thu, 09 Jan 2014 02:30:31 GMT</volatile>
+Transfer-Encoding: chunked
+
+<strong class='highlight1'>Basic xpath usage</strong></code></pre>
+        </assertResponse>
+    </step>
+
+<p>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
+<code>title</code> nodes to get past the first stub.</p>
+
+    <step type='http'>
+<pre><code>POST / HTTP/1.1
+Host: localhost:4545
+
+&lt;books xmlns:isbn=&quot;http://schemas.isbn.org/ns/1999/basic.dtd&quot;&gt;
+  &lt;book&gt;
+    &lt;isbn:title&gt;Game of Thrones&lt;/isbn:title&gt;
+    <strong class='highlight2'>&lt;isbn:summary&gt;Dragons and political intrigue&lt;/isbn:summary&gt;</strong>
+  &lt;/book&gt;
+  &lt;book&gt;
+    &lt;isbn:title&gt;Harry Potter&lt;/isbn:title&gt;
+    <strong class='highlight2'>&lt;isbn:summary&gt;Dragons and a boy wizard&lt;/isbn:summary&gt;</strong>
+  &lt;/book&gt;
+  &lt;book&gt;
+    &lt;isbn:title&gt;The Hobbit&lt;/isbn:title&gt;
+    &lt;isbn:summary&gt;A dragon and short people&lt;/isbn:summary&gt;
+  &lt;/book&gt;
+&lt;/books&gt;</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 200 OK
+Connection: close
+Date: <volatile>Thu, 09 Jan 2014 02:30:31 GMT</volatile>
+Transfer-Encoding: chunked
+
+<strong class='highlight2'>xpath with namespaces</strong></code></pre>
+        </assertResponse>
+    </step>
+
+<p>The third stub will only match on a <code>first</code> 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.</p>
+
+    <step type='http'>
+<pre><code>POST / HTTP/1.1
+Host: localhost:4545
+
+&lt;books count=&quot;3&quot; xmlns:isbn=&quot;http://schemas.isbn.org/ns/1999/basic.dtd&quot;&gt;
+  &lt;book&gt;
+    &lt;title <strong class='highlight3'>first=&quot;false&quot;</strong>&gt;Game of Thrones&lt;/title&gt;
+    &lt;isbn:summary&gt;Dragons and political intrigue&lt;/isbn:summary&gt;
+  &lt;/book&gt;
+  &lt;book&gt;
+    &lt;title <strong class='highlight3'>first=&quot;false&quot;</strong>&gt;Harry Potter&lt;/title&gt;
+    &lt;isbn:summary&gt;Dragons and a boy wizard&lt;/isbn:summary&gt;
+  &lt;/book&gt;
+  &lt;book&gt;
+    &lt;title <strong class='highlight3'>first=&quot;true&quot;</strong>&gt;The Hobbit&lt;/title&gt;
+    &lt;isbn:summary&gt;A dragon and short people&lt;/isbn:summary&gt;
+  &lt;/book&gt;
+&lt;/books&gt;</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 200 OK
+Connection: close
+Date: <volatile>Thu, 09 Jan 2014 02:30:31 GMT</volatile>
+Transfer-Encoding: chunked
+
+<strong class='highlight3'>xpath with attributes and the quirks of deepEquals</strong></code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/4545 HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json</code>
+    </step>
+</testScenario>
+
+<%- include('../../_footer') -%>