@mbtest/mountebank 2.9.2-beta.9050

package/src/views/docs/api/behaviors/copy.ejs

@@ -0,0 +1,427 @@
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Type</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>copy</code></td>
+    <td>An object</td>
+    <td>An object specifying the request field and response token, as well as a way
+    of selecting the value from the request field</td>
+  </tr>
+  <tr>
+    <td><code>copy.from</code></td>
+    <td>A string or an object</td>
+    <td>The name of the request field to copy from, or, if the request field is an object,
+    then an object specifying the path to the request field. For example,
+    <pre><code>{ "from": "body" }</code></pre> and <pre><code>{ "from": { "query": "q" } }</code></pre>
+    are both valid.</td>
+  </tr>
+  <tr>
+    <td><code>copy.into</code></td>
+    <td>A string</td>
+    <td>The token to replace in the response with the selected request value. There is
+    no need to specify which field in the response the token will be in; all response
+    tokens will be replaced in all response fields. Sometimes, the request selection
+    returns multiple values. In those cases, you can add an index to the token, while
+    the unindexed token represents the first match. For example, if you specify
+    <pre><code>{ "into": "${NAME}" }</code></pre> as your token configuration, then both
+    <code>${NAME}</code> and <code>${NAME}[0]</code> will be replaced by the first match,
+    <code>${NAME}[1]</code> will be replaced by the second match, and so on.</td>
+  </tr>
+  <tr>
+    <td><code>copy.using</code></td>
+    <td>An object</td>
+    <td>The configuration needed to select values from the response</td>
+  </tr>
+  <tr>
+    <td><code>copy.using.method</code></td>
+    <td>An string</td>
+    <td>The method used to select the value(s) from the request. Allowed values are <code>regex</code>,
+    <code>xpath</code>, and <code>jsonpath</code>.</td>
+  </tr>
+  <tr>
+    <td><code>copy.using.selector</code></td>
+    <td>An string</td>
+    <td>The selector used to select the value(s) from the request. For a <code>regex</code>, this would
+    be the pattern, and the replacement value will be the entire match. Match groups using parentheses are supported
+    and can be replaced using indexed tokens as described in the <code>copy[].into</code> description.
+    <code>xpath</code> and <code>jsonpath</code> selectors work on XML and JSON documents. If the request
+    value does not match the selector (including through XML or JSON parsing errors), nothing is replaced.</td>
+  </tr>
+  <tr>
+    <td><code>copy.using.ns</code></td>
+    <td>An object</td>
+    <td>For <code>xpath</code> selectors, the <code>ns</code> object maps namespace aliases to URLs</td>
+  </tr>
+  <tr>
+    <td><code>copy.using.options</code></td>
+    <td>An object</td>
+    <td>For <code>regex</code> selectors, the <code>options</code> object describes the regular expression options</td>
+  </tr>
+  <tr>
+    <td><code>copy.using.options.ignoreCase</code></td>
+    <td>A boolean</td>
+    <td>Uses a <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/ignoreCase'>case-insensitive</a>
+    regular expression</td>
+  </tr>
+  <tr>
+    <td><code>copy.using.options.multiline</code></td>
+    <td>A boolean</td>
+    <td>Uses a <a href='https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp/multiline'>multiline</a>
+    regular expression</td>
+  </tr>
+</table>
+
+<p>The <code>copy</code> behavior supports dynamically replacing values in the response with something that
+comes from the request. It relies on you adding tokens of your own choosing into the response fields you want
+replaced. We'll look at the following examples:</p>
+
+<ul class='bullet-list'>
+  <li><a href='#copy-regex-replacement'>Regular expressions</a></li>
+  <li><a href='#copy-xpath-replacement'>xpath</a></li>
+  <li><a href='#copy-jsonpath-replacement'>jsonpath</a></li>
+  <li><a href='#copy-indexed-replacement'>Using match groups and indexed replacements</a></li>
+</ul>
+
+<h3 id='copy-regex-replacement'>Regular expressions</h3>
+
+<p>The following example shows multiple regular expression matches on request fields to copy into the response.</p>
+
+<testScenario name='copy-regex'>
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json
+Content-Type: application/json
+
+{
+  "port": 8585,
+  "protocol": "http",
+  "stubs": [
+    {
+      "responses": [
+        {
+          "is": {
+            "statusCode": "<strong class='highlight1'>${code}</strong>",
+            "headers": {
+              "X-Test": "<strong class='highlight2'>${header}</strong>"
+            },
+            "body": "The request name was <strong class='highlight3'>${name}</strong>. Hello, <strong class='highlight3'>${name}</strong>!"
+          },
+          "behaviors": [
+            {
+              "copy": {
+                "from": "path",
+                "into": "<strong class='highlight1'>${code}</strong>",
+                "using": { "method": "regex", "selector": "\\d+" }
+              }
+            },
+            {
+              "copy": {
+                "from": { "headers": "X-Request" },
+                "into": "<strong class='highlight2'>${header}</strong>",
+                "using": { "method": "regex", "selector": ".+" }
+              }
+            },
+            {
+              "copy": {
+                "from": { "query": "name" },
+                "into": "<strong class='highlight3'>${name}</strong>",
+                "using": {
+                  "method": "regex",
+                  "selector": "MOUNT\\w+$",
+                  "options": { "ignoreCase": true }
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}</code></pre>
+    </step>
+
+<p>This example shows off many of the options of the <code>copy</code> behavior. For example,
+we can plug tokens into any of the response fields (including the <code>statusCode</code>), and
+it shows how to navigate object request fields, like the <code>name</code> querystring
+parameter. It shows an example of using regular expressions options to get a case-insensitive
+regular expression to capture the <code>name</code> query parameter. It also shows matching multiple
+request fields using an array of <code>copy</code> configurations. Let's see what happens when we
+craft a request to match all of those selectors:</p>
+
+    <step type='http'>
+<pre><code>GET /statusCode/<strong class='highlight1'>400</strong>?ignore=this&<strong class='highlight3'>name=mountebank</strong> HTTP/1.1
+Host: localhost:8585
+X-REQUEST: <strong class='highlight2'>Header value</strong></code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 <strong class='highlight1'>400</strong> Bad Request
+X-Test: <strong class='highlight2'>Header value</strong>
+Connection: close
+Date: <volatile>Thu, 28 Dec 2016 11:37:31 GMT</volatile>
+Transfer-Encoding: chunked
+
+The request name was <strong class='highlight3'>mountebank</strong>. Hello, <strong class='highlight3'>mountebank</strong>!</code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/8585 HTTP/1.1
+Host: localhost:<%= port %></code>
+    </step>
+</testScenario>
+
+<h3 id='copy-xpath-replacement'>xpath</h3>
+
+<p>The following example shows a simple namespaced xpath match to grab the first <code>title</code> field in
+an XML document and copy it into the <code>BOOK</code> response token.</p>
+
+<testScenario name='copy-xpath'>
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json
+Content-Type: application/json
+
+{
+  "port": 8586,
+  "protocol": "http",
+  "stubs": [
+    {
+      "responses": [
+        {
+          "is": {
+            "body": "Have you read <strong class='highlight1'>BOOK</strong>?"
+          },
+          "behaviors": [
+            {
+              "copy": {
+                "from": "body",
+                "into": "<strong class='highlight1'>BOOK</strong>",
+                "using": {
+                  "method": "xpath",
+                  "selector": "//isbn:title",
+                  "ns": {
+                    "isbn": "http://schemas.isbn.org/ns/1999/basic.dtd"
+                  }
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}</code></pre>
+    </step>
+
+<p>The <code>ns</code> object map is optional and can be ignored if your xpath selector doesn't depend on
+namespaces. It doesn't matter how many <code>name</code> elements exist in the XML. Without using indexed
+tokens, only the first match will be used:</p>
+
+    <step type='http'>
+<pre><code>POST /names HTTP/1.1
+Host: localhost:8586
+
+&lt;books xmlns:isbn=&quot;http://schemas.isbn.org/ns/1999/basic.dtd&quot;&gt;
+  &lt;book&gt;
+    &lt;isbn:title&gt;<strong class='highlight1'>Game of Thrones</strong>&lt;/isbn:title&gt;
+    &lt;isbn:summary&gt;Dragons and political intrigue&lt;/isbn:summary&gt;
+  &lt;/book&gt;
+  &lt;book&gt;
+    &lt;isbn:title&gt;Harry Potter&lt;/isbn:title&gt;
+    &lt;isbn:summary&gt;Dragons and a boy wizard&lt;/isbn:summary&gt;
+  &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, 28 Dec 2016 11:37:31 GMT</volatile>
+Transfer-Encoding: chunked
+
+Have you read <strong class='highlight1'>Game of Thrones</strong>?</code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/8586 HTTP/1.1
+Host: localhost:<%= port %></code>
+    </step>
+</testScenario>
+
+<h3 id='copy-jsonpath-replacement'>jsonpath</h3>
+
+<p>The following example translates the XML example above into JSON. To make it more interesting,
+we'll show it using the <code>tcp</code> protocol</p>
+
+<testScenario name='copy-jsonpath'>
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json
+Content-Type: application/json
+
+{
+  "port": 8587,
+  "protocol": "tcp",
+  "stubs": [
+    {
+      "responses": [
+        {
+          "is": {
+            "data": "Have you read <strong class='highlight1'>BOOK</strong>?"
+          },
+          "behaviors": [
+            {
+              "copy": {
+                "from": "data",
+                "into": "<strong class='highlight1'>BOOK</strong>",
+                "using": {
+                  "method": "jsonpath",
+                  "selector": "$..title"
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}</code></pre>
+    </step>
+
+<p>Again, by default only the first match will be used:</p>
+
+    <step type='exec'>
+<pre><code>echo '{
+  "books": [
+    {
+      "title": "<strong class='highlight1'>Game of Thrones</strong>",
+      "summary": "Dragons and political intrigue"
+    },
+    {
+      "title": "Harry Potter",
+      "summary": "Dragons and a boy wizard"
+    },
+    {
+      "title": "The Hobbit",
+      "summary": "A dragon and short people"
+    }
+  ]
+}' | nc localhost 8587</code></pre>
+
+        <assertResponse>
+<pre><code>Have you read <strong class='highlight1'>Game of Thrones</strong>?</code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<code>DELETE /imposters/8587 HTTP/1.1
+Host: localhost:<%= port %></code>
+    </step>
+</testScenario>
+
+<h3 id='copy-indexed-replacement'>Indexed replacements</h3>
+
+<p>Finally, let's show an example that uses multiple matches for a given selector. To
+show that the same approach works for multiple selection methods, we'll show it for both
+regular expressions and jsonpath:</p>
+
+<testScenario name='copy-indexed'>
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json
+Content-Type: application/json
+
+{
+  "port": 8588,
+  "protocol": "http",
+  "stubs": [
+    {
+      "responses": [
+        {
+          "is": {
+            "body": "<strong class='highlight2'>${BOOK}[1]</strong>: <strong class='highlight1'>${SUMMARY}[0]</strong>\n<strong class='highlight2'>${BOOK}[2]</strong>: <strong class='highlight1'>${SUMMARY}[1]</strong>\n<strong class='highlight2'>${BOOK}[3]</strong>: <strong class='highlight1'>${SUMMARY}[2]</strong>"
+          },
+          "behaviors": [
+            {
+              "copy": {
+                "from": "body",
+                "into": "<strong class='highlight1'>${SUMMARY}</strong>",
+                "using": {
+                  "method": "jsonpath",
+                  "selector": "$..summary"
+                }
+              }
+            },
+            {
+              "copy": {
+                "from": { "query": "books" },
+                "into": "<strong class='highlight2'>${BOOK}</strong>",
+                "using": {
+                  "method": "regex",
+                  "selector": "([^,]+),([^,]+),(.+)$"
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}</code></pre>
+    </step>
+
+<p>Note the mismatched indexes between the two selection methods. This is because we use the standard regular
+expression semantics around matched groups, which is that the first element in the matches will be the entire
+matched expression, the second element will be the first parenthesized match group, and so on. Also note that
+<code>${SUMMARY}[0]</code> and <code>${SUMMARY}</code> will be treated identically.   We'll
+trigger the substitutions with the following request:</p>
+
+    <step type='http'>
+<pre><code>POST /?books=<strong class='highlight2'>Game%20of%20Thrones</strong>,<strong class='highlight2'>Harry%20Potter</strong>,<strong class='highlight2'>The%20Hobbit</strong> HTTP/1.1
+Host: localhost:8588
+
+{
+  "books": [
+    {
+      "title": "Game of Thrones",
+      "summary": "<strong class='highlight1'>Dragons and political intrigue</strong>"
+    },
+    {
+      "title": "Harry Potter",
+      "summary": "<strong class='highlight1'>Dragons and a boy wizard</strong>"
+    },
+    {
+      "title": "The Hobbit",
+      "summary": "<strong class='highlight1'>A dragon and short people</strong>"
+    }
+  ]
+}</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 200 OK
+Connection: close
+Date: <volatile>Thu, 28 Dec 2016 11:37:31 GMT</volatile>
+Transfer-Encoding: chunked
+
+<strong class='highlight2'>Game of Thrones</strong>: <strong class='highlight1'>Dragons and political intrigue</strong>
+<strong class='highlight2'>Harry Potter</strong>: <strong class='highlight1'>Dragons and a boy wizard</strong>
+<strong class='highlight2'>The Hobbit</strong>: <strong class='highlight1'>A dragon and short people</strong></code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/8588 HTTP/1.1
+Host: localhost:<%= port %></code>
+    </step>
+</testScenario>

package/src/views/docs/api/behaviors/decorate.ejs

@@ -0,0 +1,182 @@
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Type</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>decorate</code></td>
+    <td>A string</td>
+    <td>The <code>decorate</code> function, used to transform the response through JavaScript. It can either
+    mutate the response in place or return a new response object.
+
+    <p class='warning-icon'>The <code><a href='/docs/commandLine'>--allowInjection</a></code> command
+      line flag must be set to support this behavior.</p>
+    </td>
+  </tr>
+</table>
+
+<p>The <code>decorate</code> function should take a single parameter, which will contain the following fields:</p>
+
+<table>
+    <tr>
+        <th>Field</th>
+        <th>Description</th>
+    </tr>
+    <tr>
+        <td><code>request</code></td>
+        <td>The entire request object, containing all request fields</td>
+    </tr>
+    <tr>
+        <td><code>response</code></td>
+        <td>The entire response object</td>
+    </tr>
+    <tr>
+        <td><code>state</code></td>
+        <td>An initially empty object, scoped to the imposter, that will be shared with
+        <a href='/docs/api/injection#predicate-injection'>predicate</a> and
+        <a href='/docs/api/injection#response-injection'>response injection</a> functions.
+        You can use it to capture and mutate shared state.</td>
+    </tr>
+    <tr>
+        <td><code>logger</code></td>
+        <td>A logger object with <code>debug</code>, <code>info</code>, <code>warn</code>,
+        and <code>error</code> functions to write to the mountebank logs.</td>
+    </tr>
+</table>
+
+<p>The <code>decorate</code> behavior is quite powerful, allowing nearly unlimited (synchronous) post-processing
+of the response.  Since it relies on JavaScript injection, the <a href='/docs/commandLine'>--allowInjection</a>
+flag must be passed in to <code>mb</code> on startup.</p>
+
+<p>Here are a couple ideas of what to do with post-processing:</p>
+
+<ul class='bullet-list'>
+  <li><a href='#add-timestamp'>Add the current time to a response</a></li>
+  <li><a href='#add-custom-header'>Add a custom header to a proxied response</a></li>
+</ul>
+
+<h3 id='add-timestamp'>Add the current time to a response</h3>
+
+<p>Many people store static imposter files and load them via the <a href='/docs/commandLine'>--configfile</a>
+command line switch.  The <code>decorate</code> behavior supports an elegant way of adding dynamic data
+to the responses.  Let's add the current timestamp to each response.  We'll pass in a stringified version
+of the following JavaScript function:</p>
+
+<testScenario name='decorate'>
+<pre><code>(config) => {
+    var pad = function (number) {
+            return (number &lt; 10) ? '0' + number : number.toString();
+        },
+        now = new Date(),
+        time = pad(now.getHours()) + ':' + pad(now.getMinutes()) + ':' + pad(now.getSeconds());
+
+    config.response.body = config.response.body.replace('${TIME}', time);
+}</code></pre>
+
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json
+Content-Type: application/json
+
+{
+  "port": 5545,
+  "protocol": "http",
+  "stubs": [
+    {
+      "responses": [
+        {
+          "is": {
+            "body": "The time is <strong class='highlight1'>${TIME}</strong>"
+          },
+          "behaviors": [
+            { "decorate": "(config) => { var pad = function (number) { return (number &lt; 10) ? '0' + number : number.toString(); }, now = new Date(), time = pad(now.getHours()) + ':' + pad(now.getMinutes()) + ':' + pad(now.getSeconds()); config.response.body = config.response.body.replace('${TIME}', time); }" }
+          ]
+        }
+      ]
+    }
+  ]
+}</code></pre>
+    </step>
+
+<p>Now we can call the imposter to get the current time.</p>
+
+    <step type='http'>
+<pre><code>GET / HTTP/1.1
+Host: localhost:5545</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
+
+The time is <volatile><strong class='highlight1'>16:43:02</strong></volatile></code></pre>
+        </assertResponse>
+    </step>
+
+<h3 id='add-custom-header'>Add a custom header to a proxied response</h3>
+
+<p><a href='/docs/api/proxies'>Proxying</a> provides considerable power out of the box.  However,
+there are times where you need to augment the proxied response with something else to properly
+simulate your testing scenario.  In this example, we'll proxy to the
+<a href='#add-timestamp'>example above</a> (port 5545) that adds the current time to the response body.
+We'll augment the proxied response with a custom header.  Here's the decorator function, passed
+into the imposter creation as a string:</p>
+
+<pre><code>(config) => {
+    config.response.headers['X-Test'] = 'True';
+}</code></pre>
+
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json
+Content-Type: application/json
+
+{
+  "port": 7545,
+  "protocol": "http",
+  "stubs": [
+    {
+      "responses": [
+        {
+          "proxy": { "to": "http://localhost:5545" },
+          "behaviors": [
+            { "decorate": "(config) => { <strong class='highlight1'>config.response.headers['X-Test'] = 'True';</strong> }" }
+          ]
+        }
+      ]
+    }
+  ]
+}</code></pre>
+    </step>
+
+<p>Now we should get the custom header back:</p>
+
+    <step type='http'>
+<pre><code>GET /test HTTP/1.1
+Host: localhost:7545</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
+<strong class='highlight1'>X-Test: True</strong>
+
+The time is <volatile>17:16:23</volatile></code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/5545 HTTP/1.1
+Host: localhost:<%= port %></code>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/7545 HTTP/1.1
+Host: localhost:<%= port %></code>
+    </step>
+</testScenario>