@mbtest/mountebank 2.9.2-beta.9050

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

@@ -0,0 +1,191 @@
+<%
+title = 'proxies'
+description = 'Using mountebank to record and playback through proxying to a real network dependency'
+%>
+
+<%- include('../../_header') -%>
+
+<h1>Proxies</h1>
+
+<p>Proxies are one of the most powerful features of mountebank, rivaled only by the
+mighty <a href='/docs/api/injection'>injection.</a>  Proxies support record/replay
+behavior to easily capture a rich set of test data for your test scenarios.
+Each proxy definition allows you to define the fields which should be included
+in newly created <code>predicates</code>.</p>
+
+<p><code>proxy</code> response types take the following parameters:</p>
+
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th style='min-width: 4em;'>Default</th>
+    <th>Type</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>to</code></td>
+    <td>required</td>
+    <td>A URL without the path (e.g. http://someserver:3000 or tcp://someserver:3000)</td>
+    <td>Defines the origin server that the request should proxy to.</td>
+  </tr>
+  <tr>
+    <td><code>predicateGenerators</code></td>
+    <td><code>[]</code></td>
+    <td>array</td>
+    <td>An array of objects that defines how the predicates for new stubs are created. Each object in
+    the array defines the fields to generate predicates from. See <a href='#proxy-predicate-generators'>below</a>
+    for examples.</td>
+  </tr>
+  <tr>
+    <td><code>mode</code></td>
+    <td><code>proxyOnce</code></td>
+    <td>string, one of <code>proxyOnce</code>, <code>proxyAlways</code> or <code>proxyTransparent</code>.</td>
+    <td>Defines the replay behavior of the proxy. The default <code>proxyOnce</code> mode
+        doesn't require you to explicitly do anything to replay the proxied responses. The
+        <code>proxyAlways</code> mode requires you to run the
+        <a href='/docs/commandLine'><code>mb replay</code></a> command (or equivalent) to
+        switch from record mode to replay mode, but allows a richer set of data to be
+        recorded. The <code>proxyTransparent</code> mode proxies the request but does not record any data.
+        See <a href='#proxy-modes'>below</a> for details.</td>
+  </tr>
+  <tr>
+    <td><code>addWaitBehavior</code></td>
+    <td><code>false</code></td>
+    <td>boolean</td>
+    <td>If true, mountebank will add a <a href='/docs/api/behaviors#behavior-wait'><code>wait</code></a>
+    behavior to the response with the same latency that the proxied call took. This is useful in performance
+    testing scenarios where you want to simulate the actual latency of downstream services that you're
+    virtualizing.</td>
+  </tr>
+  <tr>
+    <td><code>addDecorateBehavior</code></td>
+    <td><code>null</code></td>
+    <td>string, JavaScript</td>
+    <td>If defined, mountebank will add a <a href='/docs/api/behaviors#behavior-decorate'><code>decorate</code></a>
+    behavior to the saved response.</td>
+  </tr>
+</table>
+
+<p>http and https proxies add additional optional parameters:</p>
+
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th style='min-width: 4em;'>Default</th>
+    <th>Type</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>cert</code></td>
+    <td><code>null</code></td>
+    <td>A PEM-formatted string</td>
+    <td>The SSL client certificate</td>
+  </tr>
+  <tr>
+    <td><code>key</code></td>
+    <td><code>null</code></td>
+    <td>A PEM-formatted string</td>
+    <td>The SSL client private key</td>
+  </tr>
+  <tr>
+    <td><code>ciphers</code></td>
+    <td><a href='https://nodejs.org/dist/latest-v14.x/docs/api/tls.html#tls_tls_getciphers'>Here</a></td>
+    <td>A valid cipher (see <a href='https://nodejs.org/api/tls.html#tls_modifying_the_default_tls_cipher_suite'>this page</a> for formats)</td>
+    <td>For older (and insecure) https servers, this field allows you to override the cipher used to communicate</td>
+  </tr>
+  <tr>
+    <td><code>secureProtocol</code></td>
+    <td><code>TLS_method</code></td>
+    <td>A valid <a href='https://www.openssl.org/docs/man1.1.0/man7/ssl.html#Dealing-with-Protocol-Methods'>
+      OpenSSL protocol method name</a></td>
+    <td>The SSL method to use</td>
+  </tr>
+  <tr>
+    <td><code>passphrase</code></td>
+    <td><code>null</code></td>
+    <td>string</td>
+    <td>Shared passphrase used for a single private key</td>
+  </tr>
+  <tr>
+    <td><code>injectHeaders</code></td>
+    <td><code>{}</code></td>
+    <td>object</td>
+    <td>Key-value pairs of headers to inject into the proxied <i>request</i>.</td>
+  </tr>
+</table>
+
+<p>tcp proxies support the following optional configuration:</p>
+
+<table>
+  <tr>
+    <th>Parameter</th>
+    <th style='min-width: 4em;'>Default</th>
+    <th>Type</th>
+    <th>Description</th>
+  </tr>
+  <tr>
+    <td><code>keepalive</code></td>
+    <td><code>false</code></td>
+    <td>boolean</td>
+    <td>If true, mountebank will not close the connection on each proxied request</td>
+  </tr>
+</table>
+
+<p>It is occasionally useful to capture how long the original proxied request takes. mountebank
+stores the number of milliseconds for the request in the <code>_proxyResponseTime</code> field in the
+response. Setting the <code>addWaitBehavior</code> flag will add that latency to the saved response.</p>
+
+<p class='info-icon'>Note, if you use a corporate proxy, then the standard shell
+<code>http_proxy</code> or <code>https_proxy</code> environment variables will be honored.</p>
+
+<p>Select the behavior of the proxy below for a relevant example:</p>
+
+<section class='accordion'>
+  <div>
+    <a class='section-toggler'
+       id='proxy-predicate-generators' name='proxy-predicate-generators' href='#proxy-predicate-generators'>
+      Understanding predicateGenerators
+    </a>
+    <section>
+      <%- include('proxy/predicateGenerators') -%>
+    </section>
+  </div>
+  <div>
+    <a class='section-toggler'
+       id='proxy-modes' name='proxy-modes' href='#proxy-modes'>
+      Understanding proxy modes
+    </a>
+    <section>
+      <%- include('proxy/proxyModes') -%>
+    </section>
+  </div>
+  <div>
+    <a class='section-toggler'
+       id='proxy-add-wait-behavior' name='proxy-add-wait-behavior' href='#proxy-add-wait-behavior'>
+      Adding latency to the saved responses with addWaitBehavior
+    </a>
+    <section>
+      <%- include('proxy/addWaitBehavior') -%>
+    </section>
+  </div>
+  <div>
+    <a class='section-toggler'
+       id='proxy-add-decorate-behavior' name='proxy-add-decorate-behavior' href='#proxy-add-decorate-behavior'>
+      Decorating saved responses with addDecorateBehavior
+    </a>
+    <section>
+      <%- include('proxy/addDecorateBehavior') -%>
+    </section>
+  </div>
+  <div>
+    <a class='section-toggler'
+       id='proxy-inject-headers' name='proxy-inject-headers' href='#proxy-inject-headers'>
+      Changing the proxied request headers with injectHeaders
+    </a>
+    <section>
+      <%- include('proxy/injectHeaders') -%>
+    </section>
+  </div>
+</section>
+
+<%- include('../../_footer') -%>

package/src/views/docs/api/proxy/addDecorateBehavior.ejs

@@ -0,0 +1,115 @@
+<p>A <a href='/docs/api/behaviors#behavior-decorate'><code>decorate</code> behavior</a> on a
+<code>proxy</code> response affects the proxy response itself, not the saved response
+that the proxy creates. If you want to add a <code>decorate</code> behavior on the saved
+response, you do so with the <code>addDecorateBehavior</code> field.</p>
+
+<testScenario name='decorateBehavior'>
+    <step type='http'>
+<code class='hidden'>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Content-Type: application/json
+
+{
+  "port": 5002,
+  "protocol": "http",
+  "stubs": [{
+    "responses": [{
+      "is": { "body": "downstream service response" }
+    }]
+  }]
+}</code>
+    </step>
+
+<p>We'll decorate our saved responses with the following JavaScript function:</p>
+
+<pre><code>config => {
+  config.response.body = config.response.body + ' DECORATED!';
+}</code></pre>
+
+<p>Add that function in the <code>addDecorateBehavior</code> field of the proxy
+configuration:</p>
+
+    <step type='http'>
+<pre><code><span class='hidden'>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Content-Type: application/json
+
+{
+  "port": 5000,
+  "protocol": "http",
+</span>"stubs": [{
+  "responses": [{
+    "proxy": {
+      "to": "<change to='http://localhost:5002'>http://origin-server.com</change>",
+      <strong class='highlight1'>"addDecorateBehavior": "config => { config.response.body = config.response.body + ' DECORATED!'; }"</strong>
+    }
+  }]
+}]<span class='hidden'>}</span></code></pre>
+    </step>
+
+<p>Next we'll send a request to our proxy imposter to create a new saved response. Notice
+that the decorator doesn't affect the proxied response (to do that, we'd have to add the
+same function as a <code>decorate</code> behavior on the <code>proxy</code> response too):</p>
+
+    <step type='http'>
+<pre><code>GET / HTTP/1.1
+Host: <change to='localhost:5000'>origin-server.com</change></code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 200 OK
+Connection: close
+Date: <volatile>Fri, 19 May 2017 19:39:02 GMT</volatile>
+Transfer-Encoding: chunked
+
+downstream service response</code></pre>
+        </assertResponse>
+    </step>
+
+<p>If you look at the imposter configuration, you'll notice the new <code>decorate</code>
+behavior. </p>
+
+    <step type='http'>
+<code class='hidden'>GET /imposters/5000 HTTP/1.1
+Host: localhost:<%= port %></code>
+
+        <assertResponse partial='true'>
+<pre><code><span class='hidden'>{
+</span>"stubs": [
+  {
+    "predicates": [],
+    "responses": [{
+      "is": {
+        "body": "downstream service response"<change to=''>,</change>
+        <change to=''>...</change>
+      },
+      <strong class='highlight1'>"behaviors": [
+        {
+          "decorate": "config => { config.response.body = config.response.body + ' DECORATED!'; }"
+        }
+      ]</strong>
+    }]
+  },
+  {
+    "responses": [{
+      "proxy": {
+        "to": "<change to='http://localhost:5002'>http://origin-server.com</change>",
+        "addDecorateBehavior": "config => { config.response.body = config.response.body + ' DECORATED!'; }"
+      }
+    }]
+  }
+]<span class='hidden'>}</span></code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/5002 HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json</code>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/5000 HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json</code>
+    </step>
+</testScenario>

package/src/views/docs/api/proxy/addWaitBehavior.ejs

@@ -0,0 +1,96 @@
+<p>Every response saves the time it took to call the downstream service in the
+<code>_proxyResponseTime</code> field. You can tell mountebank to automatically
+translate that into a <a href='/docs/api/behaviors#behavior-wait'>wait behavior</a>,
+which will add the same latency to the saved response. This is a useful technique
+during performance testing, where you want to virtualize downstream services but
+still want realistic latencies.</p>
+
+<testScenario name='waitBehavior'>
+    <step type='http'>
+<code class='hidden'>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Content-Type: application/json
+
+{
+  "port": 6001,
+  "protocol": "http"
+}</code>
+    </step>
+
+<p>Let's create the following proxy configuration:</p>
+
+    <step type='http'>
+<pre><code><span class='hidden'>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Content-Type: application/json
+
+{
+  "port": 6000,
+  "protocol": "http",
+</span>"stubs": [{
+  "responses": [{
+    "proxy": {
+      "to": "<change to='http://localhost:6001'>http://origin-server.com</change>",
+      <strong class='highlight1'>"addWaitBehavior": true</strong>
+    }
+  }]
+}]<span class='hidden'>}</span></code></pre>
+    </step>
+
+<p>Next we'll send a request to our proxy imposter to create a new saved response:</p>
+
+    <step type='http'>
+<pre><code>GET / HTTP/1.1
+Host: <change to='localhost:6000'>origin-server.com</change></code></pre>
+    </step>
+
+<p>If you look at the imposter configuration, you'll notice the new <code>wait</code>
+behavior. The value will be the same as the <code>_proxyResponseTime</code> field, which
+means that the saved response will add the same latency as the real service.</p>
+
+    <step type='http'>
+<code class='hidden'>GET /imposters/6000 HTTP/1.1
+Host: localhost:<%= port %></code>
+
+        <assertResponse partial='true'>
+<pre><code><span class='hidden'>{
+</span>"stubs": [
+  {
+    "predicates": [],
+    "responses": [{
+      "is": {
+        "statusCode": 200,
+        <change to=''>...</change>
+        <strong class='highlight2'>"_proxyResponseTime": <volatile>219</volatile></strong>
+      },
+      <strong class='highlight1'>"behaviors": [
+        {
+          "wait": <volatile>219</volatile>
+        }
+      ]</strong>
+    }]
+  },
+  {
+    "responses": [{
+      "proxy": {
+        "to": "<change to='http://localhost:6001'>http://origin-server.com</change>",
+        "addWaitBehavior": true
+      }
+    }]
+  }
+]<span class='hidden'>}</span></code></pre>
+        </assertResponse>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/6001 HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json</code>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/6000 HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json</code>
+    </step>
+</testScenario>

package/src/views/docs/api/proxy/injectHeaders.ejs

@@ -0,0 +1,91 @@
+<p>The <code>injectHeaders</code> field allows you to modify the request headers before
+passing them on to the downstream service. To demonstrate, let's create a mirror imposter
+so we can see what headers are sent. This imposter just takes the request
+headers it receives and sends them back in the response:</p>
+
+<p class='info-icon'><code>injectHeaders</code> only work for http/s proxies</p>
+
+<testScenario name='injectHeaders'>
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Content-Type: application/json
+
+{
+  "port": 7002,
+  "protocol": "http",
+  "name": "Mirror",
+  "stubs": [{
+    "responses": [{
+      "is": { "body": "The body." },
+      "behaviors": [
+        { "decorate": "function (req, res) { res.headers = req.headers; }" }
+      ]
+    }]
+  }]
+}</code></pre>
+    </step>
+
+<p>Now let's set up another imposter that will proxy requests to the mirror imposter.
+We'll also set up the inject headers field to insert some custom headers in the outgoing request:</p>
+
+    <step type='http'>
+<pre><code>POST /imposters HTTP/1.1
+Host: localhost:<%= port %>
+Content-Type: application/json
+
+{
+  "port": 7001,
+  "protocol": "http",
+  "name": "Inject Headers",
+  "stubs": [{
+    "responses": [{
+      "proxy": {
+        "to": "http://localhost:7002",
+        <strong class='highlight1'>"injectHeaders": {
+           "X-My-Custom-Header-One": "my first value",
+           "X-My-Custom-Header-Two": "my second value"
+        }</strong>
+      }
+    }]
+  }]
+}</code></pre>
+    </step>
+
+<p>Then we send a request to our proxy imposter:</p>
+
+    <step type='http'>
+<pre><code>GET / HTTP/1.1
+Host: localhost:7001</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 200 OK
+Host: localhost:7002
+Accept: application/json
+Connection: keep-alive
+<strong class='highlight1'>X-My-Custom-Header-One: my first value
+X-My-Custom-Header-Two: my second value</strong>
+Date: <volatile>Thu, 09 Jan 2014 02:30:31 GMT</volatile>
+Transfer-Encoding: chunked
+
+The body.
+</code></pre>
+        </assertResponse>
+    </step>
+
+<p>Now we can see that the X-My-Custom-Header-One and Two headers were returned
+back to us, reflected back from the mirror imposter after being injected into
+the <i>outgoing</i> request.</p>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/7001 HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json</code>
+    </step>
+
+    <step type='http'>
+<code class='hidden'>DELETE /imposters/7002 HTTP/1.1
+Host: localhost:<%= port %>
+Accept: application/json</code>
+    </step>
+</testScenario>