@mbtest/mountebank 2.9.2-beta.9050

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

@@ -0,0 +1,220 @@
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Type</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>lookup</code></td>
+    <td>An object</td>
+    <td>An object specifying the key (copied from a request field), the data source,
+    and the response token</td>
+  </tr>
+  <tr>
+    <td><code>lookup.key</code></td>
+    <td>An object</td>
+    <td>The information on how to select the key from the request.</td>
+  </tr>
+  <tr>
+    <td><code>lookup.key.from</code></td>
+    <td>A string or an object</td>
+    <td>The name of the request field to select 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>lookup.key.using</code></td>
+    <td>An object</td>
+    <td>The configuration needed to select the key from the response</td>
+  </tr>
+  <tr>
+    <td><code>lookup.key.using.method</code></td>
+    <td>A string</td>
+    <td>The method used to select the key from the request. Allowed values are <code>regex</code>,
+    <code>xpath</code>, and <code>jsonpath</code>.</td>
+  </tr>
+  <tr>
+    <td><code>lookup.key.using.selector</code></td>
+    <td>A string</td>
+    <td>The selector used to select the key from the request. For a <code>regex</code>, this would
+    be the pattern, and the replacement value will be the entire match by default.
+    <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>lookup.key.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>lookup.key.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>lookup.key.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>lookup.key.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>
+  <tr>
+    <td><code>lookup.key.index</code></td>
+    <td>An int (defaults to 0)</td>
+    <td>Each of the selection options returns an array: <code>regex</code> returns an array of parenthesized
+    gropus (with the entire match in the 0th index), and <code>jsonpath</code> and <code>xpath</code>
+    return an array of matches. This field selects the appropriate value from the array to use as
+    the lookup key into the data source.</td>
+  </tr>
+  <tr>
+    <td><code>lookup.fromDataSource</code></td>
+    <td>An object</td>
+    <td>Configuration for the external data source to lookup data based on the key. Each
+    <code>lookup</code> configuration may only specify one data source.</td>
+  </tr>
+  <tr>
+    <td><code>lookup.fromDataSource.csv</code></td>
+    <td>An object</td>
+    <td>Configuration for using a CSV file as the data source</td>
+  </tr>
+  <tr>
+    <td><code>lookup.fromDataSource.csv.path</code></td>
+    <td>A string</td>
+    <td>The path to the CSV file, which must be readable by the <code>mb</code> process</td>
+  </tr>
+  <tr>
+    <td><code>lookup.fromDataSource.csv.keyColumn</code></td>
+    <td>A string</td>
+    <td>The header of the column to scan for a match against the key. If a match is
+    found, the entire row will be returned.</td>
+  </tr>
+  <tr>
+    <td><code>lookup.fromDataSource.csv.delimiter</code></td>
+    <td>A string(default to comma ,)</td>
+    <td>The delimiter separated colums in CSV file.</td>
+  </tr>
+  <tr>
+    <td><code>lookup.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. A successful match will return a
+    hashmap or dictionary type object, with named indexes. For example, if you specify
+    <pre><code>{ "into": "${NAME}" }</code></pre> as your token configuration, and the
+    data source returned a row containing "first" and "last" fields, then
+    <code>${NAME}["first"]</code> and <code>${NAME}["last"]</code> will be replaced by
+    the appropriate data. You can quote the field name with double quotes, single quotes,
+    or no quotes at all.</td>
+  </tr>
+</table>
+
+<p>The <code>lookup</code> behavior supports dynamically replacing values in the response with something that
+comes from an external data source. Looking up the values from the data source requires first selecting
+the key value from the request. The key selection and replacement behavior in the response mirrors the
+functionality for the <code>copy</code> behavior. We'll look at the following examples:</p>
+
+<ul class='bullet-list'>
+  <li><a href='#lookup-regex-replacement'>Lookup up from a CSV file based on a key selected with a regular expression</a></li>
+</ul>
+
+<p class='info-icon'>Look at the <code>copy</code> examples to see how to do advanced key
+selection using jsonpath and xpath.</p>
+
+<testScenario name='lookup'>
+
+<p>We'll use the following CSV file for these examples, saved as "values.csv" in the
+current working directory of the <code>mb</code> process (you can always use an absolute path):</p>
+
+    <step type='file' filename='<%= process.cwd() %>/values.csv'>
+<pre><code>State_ID,code,Name,price,tree,jobs
+1111111,400,liquid,235651,mango,farmer
+9856543,404,solid,54564564,orange,miner
+2222222,500,water,12564,pine,shepherd
+1234564,200,plasma,2656,guava,lumberjack
+9999999,200,lovers,9999,dogwood,steel worker</code></pre>
+    </step>
+
+<h3 id='lookup-regex-replacement'>Lookup up from a CSV file based on a key selected with a regular expression</h3>
+
+<p>The following example shows selecting the key using a regular expression to match against the path. We're
+using the <code>index</code> field to select the first parenthesized group in the regular expression.</p>
+
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json
+Content-Type: application/json
+
+{
+  "port": 9595,
+  "protocol": "http",
+  "stubs": [
+    {
+      "responses": [
+        {
+          "is": {
+            "statusCode": "<strong class='highlight1'>${row}['code']</strong>",
+            "headers": {
+              "X-Tree": "<strong class='highlight1'>${row}['tree']</strong>"
+            },
+            "body": "Hello <strong class='highlight1'>${row}['Name']</strong>, have you done your <strong class='highlight1'>${row}['jobs']</strong> today?"
+          },
+          "behaviors": [
+            {
+              "lookup": {
+                "key": <strong class='highlight2'>{
+                  "from": "path",
+                  "using": { "method": "regex", "selector": "/(.*)$" },
+                  "index": 1
+                }</strong>,
+                "fromDataSource": {
+                  "csv": {
+                    "path": "<%= process.cwd() %>/values.csv",
+                    "keyColumn": "Name",
+                    "delimiter": ","
+                  }
+                },
+                "into": "<strong class='highlight1'>${row}</strong>"
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}</code></pre>
+    </step>
+
+<p>As with the <code>copy</code> behavior, we can plug tokens into any of the response fields
+(including the <code>statusCode</code>). Let's see what happens when we craft a request to match
+all of those selectors:</p>
+
+    <step type='http'>
+<pre><code>GET /<strong class='highlight2'>liquid</strong> HTTP/1.1
+Host: localhost:9595</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 <strong class='highlight1'>400</strong> Bad Request
+X-Tree: <strong class='highlight1'>mango</strong>
+Connection: close
+Date: <volatile>Thu, 28 Dec 2016 11:37:31 GMT</volatile>
+Transfer-Encoding: chunked
+
+Hello <strong class='highlight1'>liquid</strong>, have you done your <strong class='highlight1'>farmer</strong> today?</code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/9595 HTTP/1.1
+Host: localhost:<%= port %></code>
+    </step>
+
+    <step type='file' filename='<%= process.cwd() %>/values.csv' delete='true'><code>
+    </code></step>
+</testScenario>

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

@@ -0,0 +1,153 @@
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Type</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>shellTransform</code></td>
+    <td>A string</td>
+    <td>Represents the path to a command line application. The application should
+        retrieve the JSON-encoded <code>request</code> and <code>response</code> from the environment
+        and print out the transformed <code>response</code> to <code>stdout</code>.
+
+    <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>shellTransform</code> behavior plays a similar role as the <code>decorate</code> behavior,
+enabling a programmatic transformation of the response. However, you don't have to write the transformation
+logic in JavaScript -- it can be in the language of your choice.</p>
+
+<p class='warning-icon'>Since it allows shelling out to another application,
+the <a href='/docs/commandLine'>--allowInjection</a> flag must be passed in to <code>mb</code> on startup.</p>
+
+<p>mountebank will expose the following environment variables to your shell application:</p>
+
+<ul class='bullet-list'>
+    <li><code>MB_REQUEST</code> which contains the JSON request as a string, and</li>
+    <li><code>MB_RESPONSE</code> which contains the current JSON response as a string</li>
+</ul>
+
+<p>The application should write to stdout a JSON representation of
+the transformed response.</p>
+
+<p>We'll show a simple example of shelling out to plug in response values based on an external data source.</p>
+
+<h3 id='external-datasource'>Using an external data source</h3>
+
+<p>At times you may find it convenient to use an external data store to fill in dynamic values based on
+data coming in from the request. You can combine an <code>is</code> canned response with a
+<code>shellTransform</code> behavior to achieve this, regardless of what the external data source is.
+For this example, we'll assume it's a simple pipe-delimited file mapping customer ids to names. We'll
+save it as <code>names.csv</code> in the directory we run <code>mb</code> from.</p>
+
+<p class='info-icon'>Note that, by reformatting the file, this example would more easily be satisfied
+by the <code>lookup</code> behavior.</p>
+
+<testScenario name='shellTransform'>
+    <step type='file' filename='<%= process.cwd() %>/names.txt'>
+<pre><code>123|Frodo Baggins
+234|Samwise Gamgee
+345|Gandalf the White
+456|Smeagol</code></pre>
+    </step>
+
+<p>We expect the incoming http request to specify the id in the URL, and we want to represent the name
+in the response body. We'll set up our imposter like this:</p>
+
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json
+Content-Type: application/json
+
+{
+  "port": 5555,
+  "protocol": "http",
+  "stubs": [
+    {
+      "predicates": [{ "matches": { "path": "/accounts/\\d+" } }],
+      "responses": [
+        {
+          "is": { "body": "Hello, <strong class='highlight1'>${YOU}!</strong>" },
+          "behaviors": [
+            { "shellTransform": "node <%= process.cwd() %>/addName.js" }
+          ]
+        }
+      ]
+    }
+  ]
+}
+</code></pre>
+    </step>
+
+<p>In this example, we're shelling out to a node.js application, which isn't much different than
+using a <code>decorate</code> function. However, that's just to keep it simple; the application
+could be written in any language.</p>
+
+<p>Let's create the <code>addName.js</code> file..</p>
+
+    <step type='file' filename='<%= process.cwd() %>/addName.js'>
+<pre><code>var request = JSON.parse(process.env.MB_REQUEST),
+    response = JSON.parse(process.env.MB_RESPONSE),
+    requestId = request.path.replace('/accounts/', ''),
+    fs = require('fs'),
+    mappings = fs.readFileSync('<%= process.cwd() %>/names.txt', { encoding: 'utf8' }),
+    lines = mappings.split(/\r?\n/);
+
+for (let i = 0; i &lt; lines.length; i += 1) {
+    var fields = lines[i].split('|'),
+        id = fields[0],
+        name = fields[1];
+
+    if (requestId === id) {
+        <strong class='highlight1'>response.body = response.body.replace('${YOU}', name);</strong>
+    }
+}
+
+console.log(JSON.stringify(response));</code></pre>
+    </step>
+
+<p>Now we can test it out:</p>
+
+    <step type='http'>
+<pre><code>GET /accounts/234 HTTP/1.1
+Host: localhost:5555</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 200 OK
+Connection: close
+Date: <volatile>Wed, 07 Jan 2016 21:27:14 GMT</volatile>
+Transfer-Encoding: chunked
+
+Hello, <strong class='highlight1'>Samwise Gamgee!</strong></code></pre>
+        </assertResponse>
+    </step>
+
+<p>And again...</p>
+
+    <step type='http'>
+<pre><code>GET /accounts/456 HTTP/1.1
+Host: localhost:5555</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 200 OK
+Connection: close
+Date: <volatile>Wed, 07 Jan 2016 21:27:14 GMT</volatile>
+Transfer-Encoding: chunked
+
+Hello, <strong class='highlight1'>Smeagol!</strong></code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/5555 HTTP/1.1
+Host: localhost:<%= port %></code>
+    </step>
+
+    <step type='file' filename='<%= process.cwd() %>/names.txt' delete='true'><code></code></step>
+    <step type='file' filename='<%= process.cwd() %>/addName.js' delete='true'><code></code></step>
+</testScenario>

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

@@ -0,0 +1,121 @@
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th>Type</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>wait</code></td>
+    <td>A positive integer, or a string</td>
+    <td>If a number is passed in, mountebank will wait that number of milliseconds before returning.
+    If a string is passed in, it is expected to be a parameterless JavaScript function that returns the number
+    of milliseconds to wait.
+
+    <p class='warning-icon'>The <code><a href='/docs/commandLine'>--allowInjection</a></code> command
+      line flag must be set to support passing in a JavaScript function</p>
+    </td>
+  </tr>
+</table>
+
+<p>The <code>wait</code> behavior is conceptually quite simple.  Just pass in a number of milliseconds
+to wait into the behavior:</p>
+
+<testScenario name='wait'>
+    <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": [
+    {
+      "responses": [
+        {
+          "is": { "body": "This took at least half a second to send" },
+          "behaviors": [
+            { "wait": 500 }
+          ]
+        }
+      ]
+    }
+  ]
+}</code></pre>
+    </step>
+
+<p>Now we can call the imposter.  But have some patience, it'll take the better portion of a second
+before you'll get your response...</p>
+
+    <step type='http'>
+<pre><code>GET / HTTP/1.1
+Host: localhost:4545</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 took at least half a second to send</code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/4545 HTTP/1.1
+Host: localhost:<%= port %></code>
+    </step>
+
+<p>If a more advanced wait strategy is needed, you can also specify a function body as the wait variable.
+As long as the function returns a number, mountebank can be configured to wait a variable
+amount of time.</p>
+
+<p class='warning-icon'>The <code><a href='/docs/commandLine'>--allowInjection</a></code> command
+line flag must be set to support using a function to determine the wait time.</p>
+
+    <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": [
+    {
+      "responses": [
+        {
+          "is": { "body": "This took at least 100 to 1000 ms to send" },
+          "behaviors": [
+            { "wait": "function() { return Math.floor(Math.random() * 901) + 100; }" }
+          ]
+        }
+      ]
+    }
+  ]
+}</code></pre>
+    </step>
+
+<p>The result of the function determines the wait time:</p>
+
+    <step type='http'>
+<pre><code>GET / HTTP/1.1
+Host: localhost:4545</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 took at least 100 to 1000 ms to send</code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/4545 HTTP/1.1
+Host: localhost:<%= port %></code>
+    </step>
+</testScenario>

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

@@ -0,0 +1,141 @@
+<%
+title = 'behaviors'
+description = 'Additional behaviors supported by all mountebank responses'
+%>
+
+<%- include('../../_header') -%>
+
+<h1>Stub Behaviors</h1>
+
+<p>You can alter the response created by adding to the <code>behaviors</code> array, which acts as a
+middleware pipeline of transformations to the response. At the moment, mountebank accepts
+the following behaviors:</p>
+
+<table id='behaviors'>
+  <tr>
+    <th>Behavior</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>wait</code></td>
+    <td>Adds latency to a response by waiting a specified number of milliseconds before sending
+      the response.
+
+      <p class='info-icon'>Tip: Setting the <a href='/docs/api/proxies'><code>addWaitBehavior</code></a>
+      flag on proxies will automatically add this behavior with the actual time it took to call the
+      downstream service</p>
+    </td>
+  </tr>
+  <tr>
+    <td><code>copy</code></td>
+    <td>Copies one or more values from request fields into the response. You can tokenize the response
+    and select values from request fields using regular expressions, xpath, or jsonpath.</td>
+  </tr>
+  <tr>
+    <td><code>lookup</code></td>
+    <td>Queries an external data source for data based on a key selected from the request. Like the
+    <code>copy</code> behavior, you can tokenize the response and select the key from the request
+    using regular expressions, xpath, or jsonpath.</td>
+  </tr>
+  <tr>
+    <td><code>decorate</code></td>
+    <td>Post-processes the response using JavaScript injection before sending it. Post-processing opens
+      up a world of opportunities - you can use a <code>decorate</code> behavior to add data to a proxied
+      response or substitute data from the request into the response, for example.  The value passed into
+      the <code>decorate</code> behavior is a JavaScript function that can take up to three values: the
+      request, the response, and a logger.  You can either mutate the response passed in (and return nothing),
+      or return an altogether new response.
+
+      <p class='info-icon'>Tip: Setting the <a href='/docs/api/proxies'><code>addDecorateBehavior</code></a>
+      flag on proxies will automatically add this function as decorate behavior on the generated responses</p>
+
+      <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>
+  <tr>
+    <td><code>shellTransform</code></td>
+    <td>Like <code>decorate</code>, a <code>shellTransform</code> post-processes the response, but
+    instead of using JavaScript injection, it shells out to another application. That application
+    will get two command line parameters representing the request JSON and the response JSON, and
+    should print to <code>stdout</code> the transformed response JSON.
+
+    <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>Multiple behaviors can be added to a response, and they will be executed in array order. While
+each object in the array may contain only one type of behavior, you are free to repeat any
+behavior as many times as you want. For example, take a look at the following response:</p>
+
+<pre><code>{
+  "is": " { ... },
+  "behaviors": [
+    { "copy": { ... } },
+    { "decorate": "..." },
+    { "lookup": "..." },
+    { "shellTransform": "..." },
+    { "decorate": "..." },
+    { "wait": 500 },
+    { "shellTransform": "..." }
+  ]
+}</code></pre>
+
+<p>The ability to compose multiple behaviors together gives you complete control over the
+response transformation.</p>
+
+<h2>Examples</h2>
+
+<p>Select the behavior below for relevant examples, which explore each type of behavior in isolation:</p>
+
+<section class='accordion'>
+  <div>
+    <a class='section-toggler'
+       id='behavior-wait' name='behavior-wait' href='#behavior-wait'>
+      wait
+    </a>
+    <section>
+      <%- include('behaviors/wait') -%>
+    </section>
+  </div>
+  <div>
+    <a class='section-toggler'
+       id='behavior-copy' name='behavior-copy' href='#behavior-copy'>
+      copy
+    </a>
+    <section>
+      <%- include('behaviors/copy') -%>
+    </section>
+  </div>
+  <div>
+    <a class='section-toggler'
+       id='behavior-lookup' name='behavior-lookup' href='#behavior-lookup'>
+      lookup
+    </a>
+    <section>
+      <%- include('behaviors/lookup') -%>
+    </section>
+  </div>
+  <div>
+    <a class='section-toggler'
+       id='behavior-decorate' name='behavior-decorate' href='#behavior-decorate'>
+      decorate
+    </a>
+    <section>
+      <%- include('behaviors/decorate') -%>
+    </section>
+  </div>
+  <div>
+    <a class='section-toggler'
+       id='behavior-shellTransform' name='behavior-shellTransform' href='#behavior-shellTransform'>
+      shellTransform
+    </a>
+    <section>
+      <%- include('behaviors/shellTransform') -%>
+    </section>
+  </div>
+</section>
+
+<%- include('../../_footer') -%>

package/src/views/docs/api/contracts/addStub-description.ejs

@@ -0,0 +1,10 @@
+<div id='addStub-index-description'>
+  <p>The array index to add the stub. Stubs are always evaluated in array order, and the first stub
+  whose predicates match the request will be used. If you leave this value off the request, the stub
+  will be added to the end of the array.</p>
+</div>
+
+<div id='addStub-stub-description'>
+  <p>The stub to add. See the imposter contract for more information.</p>
+  <p class='info-icon'>More information: <a href='/docs/api/contracts?type=imposter'>imposter contract</a></p>
+</div>

package/src/views/docs/api/contracts/addStub.ejs

@@ -0,0 +1,10 @@
+<pre id='addStub-specification'><code>{
+<span id='addStub-index'><%- indent(2) %>&quot;index&quot;: 1,</span>
+<span id='addStub-stub'><%- indent(2) %>&quot;stub&quot;: {
+    &quot;responses&quot;: [{
+      &quot;is&quot;: {
+        &quot;body&quot;: &quot;Hello, world!&quot;
+      }
+    }]
+  }</span>
+}</code></pre>