@mbtest/mountebank 2.9.2-beta.9050

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

@@ -0,0 +1,210 @@
+<%
+title = 'jsonpath'
+description = 'Using JsonPath in mountebank predicates'
+%>
+
+<%- include('../../_header') -%>
+
+<h1>Using JSONPath</h1>
+
+<p>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 <code>jsonpath</code> predicate parameter.  This parameter narrows the scope of the predicate
+    value to a value matched by the jsonpath 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 JSON documents.  He also counsels avoiding the temptation to use it with binary protocols.</p>
+
+<p>mountebank uses the following field with jsonpath:</p>
+
+<table>
+    <tr>
+        <th>Field</th>
+        <th>Required?</th>
+        <th>Description</th>
+    </tr>
+    <tr>
+        <td><code>selector</code></td>
+        <td>Yes</td>
+        <td>The JSONPath selector</td>
+    </tr>
+</table>
+
+<p>You can send the parameter:</p>
+
+<pre><code>
+{
+    "equals": {
+        "body": "Catcher in the Rye"
+    },
+    "jsonpath": {
+        "selector": "$..title"
+    }
+}
+</code></pre>
+
+<p>The JSONPath 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 JSONPath selector can potentially match multiple nodes in the JSON
+    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>jsonpath</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='jsonpath'>
+    <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 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"
+          }
+        ]
+    }</strong>,<strong class='highlight2'>{
+        "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"
+          }
+        ]
+    }</strong>]
+}</code></pre>
+    </step>
+
+<p>The first predicate uses an jsonpath selector to navigate to all <code>title</code> elements
+    within the JSON within the <code>body</code> field.  If <code>body</code> turns out not
+    to be an JSON, 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>jsonpath</code>.  The <code>exists</code> predicate behavior is identical to its behavior with
+    other fields, except now the jsonpath 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 jsonpath 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
+
+{
+    "book":[
+      {
+        "title": "Game of Thrones",
+        "isbn:summary": "Dragons and political intrigue",
+        "author": "George R.R. Martin"
+      },
+      {
+        <strong class='highlight1'>"title": "Catcher in the Rye"</strong>,
+        "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"
+      }
+    ]
+}</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 jsonpath usage</strong></code></pre>
+        </assertResponse>
+    </step>
+
+<p>To test the second stub, we'll use deep equals to get a specific <code>title</code>
+node dependant on what book we are looking at. We can also use deep equals to get
+all the corresponding nodes.</p>
+
+    <step type='http'>
+<pre><code>POST / HTTP/1.1
+Host: localhost:4545
+
+{
+    "book":[
+      {
+        <strong class='highlight2'>"title": "Harry Potter"</strong>,
+        "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"
+      }
+    ]
+}</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'>JSONPath 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') -%>

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

@@ -0,0 +1,130 @@
+<%
+title = 'mocks'
+description = 'Using mountebank to verify network calls were made'
+%>
+
+<%- include('../../_header') -%>
+
+<h1>Mocks</h1>
+
+<p><a href='http://martinfowler.com/articles/mocksArentStubs.html'>Mocks</a> are a type
+of test double that allow you to verify a call was made without relying on the server
+response.  mountebank enables mocking through the <code>requests</code> element on
+an imposter. The fields saved for each request depends on the protocol, and are documented
+in the protocol pages linked to from the sidebar. It is up to the client code to
+implement the mock verification using the <code>requests</code> array.</p>
+
+<p class='warning-icon'>Note, you must configure the imposter to record requests by setting the
+<code>recordRequests</code> field to true to enable mock
+verification. Mocking requires mountebank to remember information about each request to each imposter.
+For long-running instances of mountebank, it is recommended that you run <code>mb</code> with the
+<code>--datadir</code> command line option so that all requests are persisted to disk. Otherwise,
+mountebank will save them to memory, which will create a significant performance constraint
+when there are a large number of requests saved. You can also manually clear an imposter's saved
+requests - see the <a href='/docs/api/overview'>overview page</a> for details.</p>
+
+<h2>Example</h2>
+
+<p>The <a href='/docs/protocols/smtp'>SMTP</a> protocol is one where mocking is very valuable,
+since most applications don't rely on complex SMTP responses, but it is useful to verify
+that the application sent an SMTP request without actually sending an email.</p>
+
+<p>First let's create an imposter:</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": "smtp",
+  "recordRequests": true
+}</code></pre>
+    </step>
+
+<p>Now make the following SMTP request in your application:</p>
+
+    <step type='smtp' port='4545'>
+<pre><code>From: "Customer Service" &lt;customer-service@company.com&gt;
+To: "Customer" &lt;customer@domain.com&gt;
+Subject: Thank you for your order
+
+Hello Customer,
+Thank you for your order from company.com.  Your order will
+be shipped shortly.
+
+Your friendly customer service department.</code></pre>
+    </step>
+
+<p>You can verify the call by making either a <code>GET</code> or
+<code>DELETE</code> call to the imposter:</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: 1116
+Date: <volatile>Thu, 09 Jan 2014 02:30:31 GMT</volatile>
+Connection: keep-alive
+
+{
+  "protocol": "smtp",
+  "port": 4545,
+  "numberOfRequests": 1,
+  "recordRequests": true,
+  <strong class='highlight1'>"requests": [
+    {
+      "requestFrom": "<volatile>127.0.0.1</volatile>",
+      "ip": "<volatile>127.0.0.1</volatile>",
+      "envelopeFrom": "customer-service@company.com",
+      "envelopeTo": ["customer@domain.com"],
+      "from": {
+        "address": "customer-service@company.com",
+        "name": "Customer Service"
+      },
+      "to": [
+        {
+          "address": "customer@domain.com",
+          "name": "Customer"
+        }
+      ],
+      "cc": [],
+      "bcc": [],
+      "subject": "Thank you for your order",
+      "priority": "normal",
+      "references": [],
+      "inReplyTo": [],
+      "text": "Hello Customer,\nThank you for your order from company.com.  Your order will\nbe shipped shortly.\n\nYour friendly customer service department.",
+      "html": "",
+      "attachments": [],
+      "timestamp": "<volatile>2015-01-09T02:30:31.850Z</volatile>"
+    }
+  ]</strong>,
+  "stubs": [],
+  "_links": {
+    "self": { "href": "http://localhost:<%= port %>/imposters/4545" },
+    "stubs": { "href": "http://localhost:<%= port %>/imposters/4545/stubs" }
+  }
+}</code></pre>
+        </assertResponse>
+    </step>
+
+    <p>Now you can use the <code>requests</code> element in your test code to validate
+the application sent the correct information.</p>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/4545 HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json</code>
+    </step>
+</testScenario>
+
+<%- include('../../_footer') -%>