@mbtest/mountebank 2.9.2-beta.9050

package/src/views/docs/cli/configFiles.ejs

@@ -0,0 +1,133 @@
+<p>The default <code>formatter</code> for mountebank allows you to use EJS (version 2.x) templates
+to split the test data into multiple files. This is particularly useful for separating out JavaScript injection
+functions and XML or JSON HTTP response bodies because you store them as multi-line files and rely on
+templating to turn them into JSON-friendly single line strings. It remains the default for backwards
+compatibility, even though EJS 3.x has made breaking changes.</p>
+
+<p>mountebank will pass a <code>stringify</code> function into your templates that allows you to put
+multi-line strings in separate files.  The example below is loosely based on the
+<a href='/docs/api/injection#response-injection'>response injection</a> example described on
+the Injection page, and shows the use of the <code>stringify</code> function. The path passed in
+to <code>stringify</code> is relative to the root file referenced in the <code>configfile</code>
+command line parameter. You can also pass a custom object, referenced as <code>data</code> in child
+templates, as the second parameter of <code>stringify</code>. This is useful if you want to reuse
+the same template but add some dynamic data. For an example, look at the <code>stringify</code> call in
+templates/originServer.ejs below, and using the custom field in templates/originXMLResponse.ejs.</p>
+
+<p>Assuming the files below are in a relative directory called <code>templates</code>, you can
+initialize <code>mb</code> with the following command:</p>
+
+<pre><code>mb --configfile templates/imposters.ejs --allowInjection --localOnly</code></pre>
+
+<p>templates/imposters.ejs</p>
+<pre><code>{
+  "imposters": [
+    &lt;% include originServer.ejs %&gt;,
+    &lt;% include proxyServer.ejs %&gt;
+  ]
+}</code></pre>
+
+<p>templates/originServer.ejs</p>
+<pre><code>{
+  "port": 5555,
+  "protocol": "http",
+  "name": "origin",
+  "stubs": [
+    {
+      "predicates": [{ "contains": { "headers": { "Content-Type": "xml" } } }],
+      "responses": [{ "is": { "body": "&lt;%- stringify('originXMLResponse.ejs', { value: 'first }) %&gt;" }}]
+    },
+    {
+      "responses": [{ "inject": "&lt;%- stringify('originServerResponse.ejs') %&gt;" }]
+    }
+  ]
+}</code></pre>
+
+<p>templates/originXMLResponse.ejs</p>
+<pre><code>&lt;rootNode&gt;
+  &lt;childNode&gt;<%= '<' + '%= data.value %' + '>' %>&lt;/childNode&gt;
+&lt;/rootNode&gt;</code></pre>
+
+<p>templates/originServerResponse.ejs</p>
+<pre><code>(request, state, logger) => {
+    logger.info('origin called');
+    state.requests = state.requests || 0;
+    state.requests += 1;
+    return {
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify({ count: state.requests })
+    };
+}</code></pre>
+
+<p>templates/proxyServer.ejs</p>
+<pre><code>{
+  "port": 4546,
+  "protocol": "http",
+  "name": "proxy",
+  "stubs": [
+    {
+      "responses": [{ "inject": "&lt;%- stringify('counter.ejs') %&gt;" }],
+      "predicates": [{
+        "equals": {
+          "method": "GET",
+          "path": "/counter"
+        }
+      }]
+    },
+    {
+      "responses": [{ "inject": "&lt;%- stringify('proxy.ejs') %&gt;" }]
+    }
+  ]
+}</code></pre>
+
+<p>templates/counter.ejs</p>
+<pre><code>function (request, state) {
+    var count = state.requests ? Object.keys(state.requests).length : 0;
+
+    return {
+        body: `There have been ${count} proxied calls`
+    };
+}</code></pre>
+
+<p>templates/proxy.ejs</p>
+<pre><code>function (request, state, logger, callback) {
+    var cacheKey = request.method + ' ' + request.path;
+
+    if (typeof state.requests === 'undefined') {
+        state.requests = {};
+    }
+
+    if (state.requests[cacheKey]) {
+        logger.info('Using previous response');
+        callback(state.requests[cacheKey]);
+    }
+
+    var http = require('http'),
+        options = {
+            method: request.method,
+            hostname: 'localhost',
+            port: 5555,
+            path: request.path,
+            headers: request.headers
+        },
+        httpRequest = http.request(options, response => {
+            var body = '';
+            response.setEncoding('utf8');
+            response.on('data', chunk => {
+                body += chunk;
+            });
+            response.on('end', () => {
+                var stubResponse = {
+                        statusCode: response.statusCode,
+                        headers: response.headers,
+                        body
+                    };
+                logger.info('Successfully proxied: ' + JSON.stringify(stubResponse));
+                state.requests[cacheKey] = stubResponse;
+                callback(stubResponse);
+            });
+        });
+    httpRequest.end();
+}</code></pre>

package/src/views/docs/cli/customFormatters.ejs

@@ -0,0 +1,53 @@
+<p>A <code>formatter</code> is a CommonJS module that exports two functions: <code>load</code>, used
+to load the configuration when the <code>configfile</code> option is passed to <code>mb start</code>,
+and <code>save</code>, used to save the configuration for <code>mb save</code>. The formatter
+gives you total control over how the test data is stored, allowing you to improve readability
+(which suffers by default from JSON's single line requirement for strings) or to convert between
+formats of other service virtualization tools.</p>
+
+<p>The <a href='https://github.com/mountebank-testing/mountebank-formatters'>default formatter</a> that ships with mountebank is
+described above ("Default config file parsing"). The example below shows a simple (and silly) formatter
+that encodes all data as Base64.</p>
+
+<pre><code>'use strict';
+
+function encode (obj) {
+    return Buffer.from(JSON.stringify(obj)).toString('base64');
+}
+
+function decode (text) {
+    return Buffer.from(text, 'base64').toString('utf8');
+}
+
+function load (options) {
+    const fs = require('fs'),
+        contents = fs.readFileSync(options.configfile, { encoding: 'utf8' });
+    return JSON.parse(decode(contents));
+}
+
+function save (options, imposters) {
+    const fs = require('fs');
+
+    if (options.customName && imposters.imposters.length > 0) {
+        imposters.imposters[0].name = options.customName;
+    }
+    fs.writeFileSync(options.savefile, encode(imposters));
+}
+
+module.exports = { load, save };</code></pre>
+
+<p class='info-icon'>All CLI options are passed to both the <code>load</code> and <code>save</code> functions, allowing
+you to define custom options specific to your formatter. You can see an example of this in the
+<code>save</code> function, which takes a <code>customName</code> option and makes it the saved
+name of the first imposter.</p>
+
+<p class='info-icon'>The code above shows a synchronous implementation, but mountebank will accept
+a promise return value.</p>
+
+<p>Assuming the module is saved as 'customFormatter.js', the following commands will use it
+for saving and loading:</p>
+
+<pre><code>mb save --savefile mb.json --formatter customFormatter
+mb restart --configfile mb.json --formatter customFormatter</code></pre>
+
+

package/src/views/docs/cli/help.ejs

@@ -0,0 +1,6 @@
+<pre><code>mb help</code></pre>
+
+<p>Lists basic command line help. You can get more detailed help for a command
+with the following:</p>
+
+<pre><code>mb <em>command</em> --help</code></pre>

package/src/views/docs/cli/replay.ejs

@@ -0,0 +1,42 @@
+<pre><code>mb replay [options]</code></pre>
+
+<p>The <code>replay</code> command is a convenience that removes all proxies,
+effectively switching from record mode to replay mode. Assuming
+mountebank is running on port 3000, you would run the following command:</p>
+
+<pre><code>mb replay --port 3000</code></pre>
+
+<p>That will reset the imposter configuration by sending a <code>PUT</code> command to /imposters
+based on the current configuration, excluding the proxies (using the
+<code>?removeProxies=true</code> query parameter). The following options are available:</p>
+
+<table>
+  <tr>
+    <th style='width: 12em;'>Option</th>
+    <th>Description</th>
+    <th>Default</th>
+  </tr>
+  <tr>
+    <td><code>--port 2525</code></td>
+    <td>The port of the running the mountebank server</td>
+    <td><code>2525</code></td>
+  </tr>
+  <tr>
+    <td><code>--host mbserver.local</code></td>
+    <td>The hostname of the running mountebank server</td>
+    <td><code>localhost</code></td>
+  </tr>
+  <tr>
+    <td><code>--rcfile .mbrc</code></td>
+    <td>The run commands file containing startup configuration (a JSON-equivalent representation
+      of the command line arguments). When the same option is listed
+    in both the <code>rcfile</code> and the command line, the command line option takes
+    precedence.</td>
+    <td><code>N/A</code></td>
+  </tr>
+  <tr>
+    <td><code>--help</code></td>
+    <td>Show help for the command</td>
+    <td><code>N/A</code></td>
+  </tr>
+</table>

package/src/views/docs/cli/restart.ejs

@@ -0,0 +1,10 @@
+<pre><code>mb restart [options]</code></pre>
+
+<p>The <code>restart</code> command is equivalent to running <code>mb stop</code> followed
+by <code>mb start</code>. To ensure a clean <code>stop</code>, the <code>--pidfile</code>
+must match the one passed to the original <code>mb start</code> process. By default,
+this means you must run <code>restart</code> in the same working directory you originally
+ran the <code>start</code> command from.</p>
+
+<p>The <code>restart</code> command has all the same command line options as the
+<code>start</code> command.</p>

package/src/views/docs/cli/save.ejs

@@ -0,0 +1,68 @@
+<pre><code>mb save [options]</code></pre>
+
+<p>While you can always use the <a href='/docs/api/overview'>API</a> to capture the current configuration
+of imposters, mountebank provides a convenient command line mechanism to save the configuration
+into a file that can be used to start a subsequent process of <code>mb</code> using the
+<code>--configfile</code> command line option. With a running <code>mb</code> process operating on port
+3000, you can execute the following command:</p>
+
+<pre><code>mb save --port 3000 --savefile saved.json --removeProxies</code></pre>
+
+<p>All of the parameters are optional with the defaults listed in the table below. You could then
+restart mountebank with the following command:</p>
+
+<pre><code>mb restart --port 3000 --configfile saved.json</code></pre>
+
+<p>The <code>save</code> command takes the following options:</p>
+
+<table>
+  <tr>
+    <th style='width: 12em;'>Option</th>
+    <th>Description</th>
+    <th>Default</th>
+  </tr>
+  <tr>
+    <td><code>--port 2525</code></td>
+    <td>The port of the running the mountebank server</td>
+    <td><code>2525</code></td>
+  </tr>
+  <tr>
+    <td><code>--host mbserver.local</code></td>
+    <td>The hostname of the running mountebank server</td>
+    <td><code>localhost</code></td>
+  </tr>
+  <tr>
+    <td><code>--savefile saved.json</code></td>
+    <td>The file to save imposters to</td>
+    <td><code>mb.json</code></td>
+  </tr>
+  <tr>
+    <td><code>--formatter path/to/module</code></td>
+    <td>Historically, mountebank was limited to saving all configuration in a single file when
+    calling <code>mb save</code>. A custom formatter allows you to save test data in whatever format
+    you want (including in ways that convert between other service virtualization products). See
+    <a href='#custom-formatters'>below</a> for more details.</td>
+    <td><a href='https://github.com/mountebank-testing/mountebank-formatters'>mountebank-formatters</a></td>
+  </tr>
+  <tr>
+    <td><code>--removeProxies</code></td>
+    <td>Remove proxies from the saved configuration, useful when you want to switch
+        from record to replay mode. Corresponds to the
+      <code><a href='/docs/api/overview#get-imposters'>removeProxies</a></code> API
+      query parameter</td>
+    <td><code>false</code></td>
+  </tr>
+  <tr>
+    <td><code>--rcfile .mbrc</code></td>
+    <td>The run commands file containing startup configuration (a JSON-equivalent representation
+    of the command line arguments). When the same option is listed
+    in both the <code>rcfile</code> and the command line, the command line option takes
+    precedence.</td>
+    <td><code>N/A</code></td>
+  </tr>
+  <tr>
+    <td><code>--help</code></td>
+    <td>Show help for the command</td>
+    <td><code>N/A</code></td>
+  </tr>
+</table>

package/src/views/docs/cli/start.ejs

@@ -0,0 +1,234 @@
+<p><code>start</code> is the default <code>mb</code> command, meaning:</p>
+
+<pre><code>mb start [options]</code></pre>
+
+<p>is identical to</p>
+
+<pre><code>mb [options]</code></pre>
+
+<p>Running <code>mb</code> by itself, without any options, will start up the API
+on port 2525. It will also spin up this website on http://localhost:2525/, giving
+you accurate documentation for the version of mountebank you're running, as the
+official site only contains the latest docs. The following options are available:</p>
+
+<table>
+  <tr>
+    <th style='width: 12em;'>Option</th>
+    <th>Description</th>
+    <th>Default</th>
+  </tr>
+  <tr>
+    <td><code>--port 2525</code></td>
+    <td>The port to run the main mountebank server on</td>
+    <td><code>2525</code></td>
+  </tr>
+  <tr>
+    <td><code>--host mbserver.local</code></td>
+    <td>The hostname to bind the main mountebank server to</td>
+    <td><em>all hosts</em></td>
+  </tr>
+  <tr>
+    <td><code>--datadir .mbdb</code></td>
+    <td>The root directory for persisting all imposter changes. When used, mountebank
+      will start all imposters saved in the directory initially and persist all operations
+      to disk in real time, significantly reducing the memory footprint.
+
+    <p class='info-icon'>This option allows you to scale imposters with multiple processes
+      (running on multiple hosts behind a load balancer to avoid port collision), with the state
+      of all processes synced in real time. All mountebank processes will need to share the same volume.</td>
+
+    <td>Without this option, all configuration will be in memory. Keeping everything in memory can be a
+    significant performance hit when there is a lot of test data, for example, during proxy recording.</td>
+  </tr>
+  <tr>
+    <td><code>--impostersRepository=./impostersRepo.js</code></td>
+    <td>Use a custom database instead of the built-in file-based data store that <code>datadir</code>
+    creates (when both are used, <code>impostersRepository</code> takes precedence). Creating
+    a custom database option is not documented and requires looking at the code, but the community
+    have created (or are creating) options. See <a href='//docs/communityExtensions'>community extensions</a>
+    for examples.</td>
+  </tr>
+  <tr>
+    <td><code>--configfile imposters.ejs</code></td>
+    <td>If present, mountebank will load the contents of the specified file.  See
+    <a href='#config-files'>below</a> for details.
+
+    <p class='warning-icon'>If both the <code>datadir</code> and <code>configfile</code> options are
+    used, mountebank will initially load all imposters from the <code>datadir</code> and then add all from
+    the <code>configfile</code>. This means that when the same imposter port is saved in both places, what
+    is in the <code>datadir</code> will be immediately overwritten by what's in the <code>configfile</code>!</p></td>
+    <td><code>N/A</code></td>
+  </tr>
+  <tr>
+    <td><code>--formatter path/to/module</code></td>
+    <td>Historically, mountebank supported EJS templating when using the <code>configfile</code> option,
+    and was limited to saving all configuration in a single file when calling <code>mb save</code>. For
+    backwards compatibility, that remains the default option, even though EJS has subsequently made
+    breaking changes.
+
+    <p>A custom formatter allows you to save test data in whatever format you want (including in ways
+    that convert between other service virtualization products). See <a href='#custom-formatters'>below</a>
+    for more details. In the context of <code>mb start</code>, the formatter will be used to parse the <code>configfile</code>.</p>
+    </td>
+    <td><a href='https://github.com/mountebank-testing/mountebank-formatters'>mountebank-formatters</a></td>
+  </tr>
+  <tr>
+    <td><code>--noParse</code></td>
+    <td>By default, mountebank will render config files through EJS templating to
+    allow modularizing rich configuration. Use this flag if you aren't using templating
+    and have special character sequences in your configuration that
+    cause rendering errors.</td>
+    <td><code>false</code></td>
+  </tr>
+  <tr>
+    <td><code>--logfile mb.log</code></td>
+    <td>The file for mountebank to store the logs in</td>
+    <td><code>mb.log</code></td>
+  </tr>
+  <tr>
+    <td><code>--loglevel debug</code></td>
+    <td>The logging level, one of <code>debug, info, warn, error</code></td>
+    <td><code>info</code></td>
+  </tr>
+  <tr>
+    <td><code>--nologfile</code></td>
+    <td>Prevent logging to the filesystem</td>
+    <td><code>false</code></td>
+  </tr>
+  <tr>
+    <td><code>--log</code></td>
+    <td>Advanced logging configuration, when you want to customize the log formats. While you
+    can pass the JSON string on the command line, it's easier to put it in the <code>rcfile</code>.
+    If you pass <code>log</code>, the simpler logging configuration options
+    (<code>loglevel</code>, <code>logfile</code>, <code>nologfile</code>) will be ignored.
+
+    <p>You can set the format to "json" to log all fields as JSON, or set it to a string to
+    customize the format. The supported fields are:</p>
+
+    <ul class='bullet-list'>
+      <li>%level</li>
+      <li>%timestamp</li>
+      <li>%message</li>
+    </ul>
+    </td>
+    <td><pre><code>{
+  "level": "info",
+  "transports": {
+    "console": {
+      "colorize": true,
+      "format": "%level: %message"
+    },
+    "file": {
+      "path": "mb.log",
+      "format": "json"
+    }
+  }
+}</code></pre></td>
+  </tr>
+  <tr>
+    <td><code>--allowInjection</code></td>
+    <td>mountebank supports JavaScript injection for <a href='/docs/api/predicates'>predicates</a>,
+      <a href='/docs/api/injection'>stub responses</a>, <a href='/docs/api/behaviors'>behavior decoration</a>,
+      <a href='/docs/api/behaviors'>wait behavior functions</a> and
+      <a href='/docs/protocols/tcp#endOfRequestResolver'>tcp request resolution</a>, but they are
+      disabled by default.  Including this parameter will enable them.
+
+      <p class='warning-icon'>Note that allowing injection means that an attacker can run random
+      code on the machine running <code>mb</code>. Please see the <a href='/docs/security'>security page</a>
+      for tips on securing your system.</p>
+    </td>
+    <td><code>false</code></td>
+  </tr>
+  <tr>
+    <td><code>--localOnly</code></td>
+    <td>Only accept requests from localhost. You should ALWAYS do this when running mountebank with
+        <code>allowInjection</code> directly on your developer machine, but will need to use
+        <code>ipWhitelist</code> otherwise (or if running in Docker),</td>
+    <td><code>false</code></td>
+  </tr>
+  <tr>
+    <td><code>--ipWhitelist</code></td>
+    <td>A pipe-delimited string of remote IP addresses to whitelist (local IP addresses will always
+    be allowed). Any request to the primary <code>mb</code> socket or an imposter socket that isn't
+    whitelisted will be dropped.</td>
+    <td><code>*</code>, representing all IP addresses</td>
+  </tr>
+  <tr>
+    <td><code>--origin</code></td>
+    <td>A safe origin for CORS requests. Use the flag multiple times to enable multiple origins.</td>
+    <td><code>false</code>, which disables CORS to prevent CSRF attacks.</td>
+  </tr>
+  <tr>
+    <td><code>--protofile</code></td>
+    <td>File to load custom <a href='/docs/protocols/custom'>protocol implementations</a> from.</td>
+    <td><code>protocols.json</code></td>
+  </tr>
+  <tr>
+    <td><code>--rcfile .mbrc</code></td>
+    <td>The run commands file containing startup configuration. The <code>rcfile</code>
+      format is a JSON-equivalent representation of the command line option. For example,
+      the following command line is very complex:
+
+<pre><code>mb --port 3000 --allowInjection --origin 'http://first.com' --origin 'http://second.com' \
+--log '{ "level": "warn", "transports": { "console": { "format": "json" } } }'</code></pre>
+
+      You could simplify it by putting the configuration in a file and running
+
+<pre><code>mb start --rcfile .mbrc</code></pre>
+
+      The file .mbrc would look like the following:
+
+<pre><code>{
+  "port": 3000,
+  "allowInjection": true,
+  "origin": ["http://first.com", "http://second.com"],
+  "log": {
+    "level": "warn",
+    "transports": {
+      "console": {
+        "format": "json"
+      }
+    }
+  }
+}</code></pre>
+
+      When the same option is listed in both the <code>rcfile</code> and the command line,
+      the command line option takes precedence.
+    </td>
+    <td><code>N/A</code></td>
+  </tr>
+  <tr>
+    <td><code>--debug</code></td>
+    <td>Include a <code>matches</code> array with each stub in the body of a
+      <a href='/docs/api/overview#get-imposter'>GET imposter</a> response
+      for debugging why a particular stub did or did not match a request.
+      Every time a response from the stub is used, a match will be added containing
+      the request, the response configuration, the actual generated response (even
+      if it is proxied), and the overall processing time.
+    <td><code>false</code></td>
+  </tr>
+  <tr>
+    <td><code>--pidfile</code></td>
+    <td>The file where the process id is stored for the <code>mb stop</code> command</td>
+    <td><code>mb.pid</code></td>
+  </tr>
+  <tr>
+    <td><code>--apikey myapikey</code></td>
+    <td>
+      An optional API key. When this is provided,
+      the Mountebank API will require that the x-api-key
+      header be supplied with a matching key.
+    </td>
+    <td><code>null</code></td>
+  </tr>
+  <tr>
+    <td><code>--version</code></td>
+    <td>Print the version out to the console and exit.</td>
+    <td><code>N/A</code></td>
+  </tr>
+  <tr>
+    <td><code>--help</code></td>
+    <td>Show help for the command</td>
+    <td><code>N/A</code></td>
+  </tr>
+</table>

package/src/views/docs/cli/stop.ejs

@@ -0,0 +1,32 @@
+<pre><code>mb stop [options]</code></pre>
+
+<p>Stops <code>mb</code>, shutting down all open sockets. Generally, <code>mb stop</code>
+must be run from the same directory as the <code>mb start</code> command, although
+that is configurable with the <code>pidfile</code> option:</p>
+
+<table>
+  <tr>
+    <th style='width: 12em;'>Option</th>
+    <th>Description</th>
+    <th>Default</th>
+  </tr>
+  <tr>
+    <td><code>--pidfile</code></td>
+    <td>The path to the pidfile, which stores the process id of the running <code>mb</code> process.
+        Must match the pidfile passed in the <code>mb start</code> command.</td>
+    <td><code>mb.pid</code></td>
+  </tr>
+  <tr>
+    <td><code>--rcfile .mbrc</code></td>
+    <td>The run commands file containing startup configuration (a JSON-equivalent representation
+      of the command line arguments). When the same option is listed
+    in both the <code>rcfile</code> and the command line, the command line option takes
+    precedence.</td>
+    <td><code>N/A</code></td>
+  </tr>
+  <tr>
+    <td><code>--help</code></td>
+    <td>Show help for the command</td>
+    <td><code>N/A</code></td>
+  </tr>
+</table>