@mbtest/mountebank 2.9.2-beta.9050

package/src/views/docs/commandLine.ejs

@@ -0,0 +1,93 @@
+<%
+title = 'command line'
+description = 'Command line parameters for starting mountebank'
+%>
+
+<%- include('../_header') -%>
+
+<h1>Configuring mountebank</h1>
+
+<p>The basic command line structure is:</p>
+
+<pre><code>mb [command=start] [options...]</code></pre>
+
+<h2>mountebank commands</h2>
+
+<p>As mountebank has grown in functionality, the number of commands and options
+has increased significantly. The links below attempt to simplify that configuration
+based on the core mountebank commands.</p>
+
+<section class='accordion'>
+  <div>
+    <a class='section-toggler' id='start' name='start' href='#start'>mb start</a>
+    <section>
+      <%- include('cli/start') -%>
+    </section>
+  </div>
+  <div>
+    <a class='section-toggler' id='stop' name='stop' href='#stop'>mb stop</a>
+    <section>
+      <%- include('cli/stop') -%>
+    </section>
+  </div>
+  <div>
+    <a class='section-toggler' id='restart' name='restart' href='#restart'>mb restart</a>
+    <section>
+      <%- include('cli/restart') -%>
+    </section>
+  </div>
+  <div>
+    <a class='section-toggler' id='save' name='save' href='#save'>mb save</a>
+    <section>
+      <%- include('cli/save') -%>
+    </section>
+  </div>
+  <div>
+    <a class='section-toggler' id='replay' name='replay' href='#replay'>mb replay</a>
+    <section>
+      <%- include('cli/replay') -%>
+    </section>
+  </div>
+  <div>
+    <a class='section-toggler' id='help' name='help' href='#help'>mb help</a>
+    <section>
+      <%- include('cli/help') -%>
+    </section>
+  </div>
+</section>
+
+<h2>Saving test data: config files and formatters</h2>
+
+<p>Note that <code>mb</code> is not persistent by default. Absent the <code>datadir</code>
+or <code>impostersRepository</code> options,
+stopping and restarting <code>mb</code> will lose all stubs and all requests. The following two
+<code>mb</code> commands work in tandem to allow you to save and reload test data:</p>
+
+<pre><code>mb save --savefile mb.json --formatter path/to/module
+mb restart --configfile mb.json --formatter path/to/module</code></pre>
+
+<p>The <code>configfile</code> sends a <a href='/docs/api/overview#change-stubs'><code>PUT</code> command</a>
+to <code>/imposters</code>. View the <a href='/docs/api/contracts?type=imposters'>JSON contract</a>
+to see what the contents should look like.</p>
+
+<p>The <code>formatter</code> is optional. If specified, it gives you total control over the format of
+the test data saved to disk, which allows you to split the content in separate files or convert
+to a format used by other service virtualization tools. The links below describe the default
+formatter for configuration files as well as how to define a custom formatter.</p>
+
+<section class='accordion'>
+    <div>
+        <a class='section-toggler' id='config-files' name='config-files' href='#config-files'>Default config file parsing</a>
+        <section>
+            <%- include('cli/configFiles') -%>
+        </section>
+    </div>
+    <div>
+        <a class='section-toggler' id='custom-formatters' name='custom-formatters' href='#custom-formatters'>Custom formatters</a>
+        <section>
+            <%- include('cli/customFormatters') -%>
+        </section>
+    </div>
+</section>
+
+<%- include('../_footer') -%>

package/src/views/docs/communityExtensions.ejs

@@ -0,0 +1,233 @@
+<%
+title = 'client libraries'
+description = 'Native client libraries for your favorite language'
+%>
+
+<%- include('../_header') -%>
+
+<h1>Client Libraries</h1>
+
+<p>While mountebank speaks <a href='/docs/api/overview'>REST</a>, he truly loves your native language
+and has no desire to make you learn another language.  If you have a native library you'd like others
+to be able to use, please send mountebank a note on the <a href='/support'>support page</a> or through
+a pull request to this page and he will add it to the list below.</p>
+
+<p>Some of these are still in their early stages.  Feel free to help the authors out ;></p>
+
+<table>
+    <tr>
+        <th>Language</th>
+        <th>Name</th>
+        <th>Author</th>
+    </tr>
+    <tr>
+        <td>C#</td>
+        <td><a href='https://github.com/mattherman/MbDotNet'>MbDotNet</a></td>
+        <td>Matthew Herman</td>
+    </tr>
+    <tr>
+        <td>Clojure</td>
+        <td><a href='https://github.com/mdaley/charlatan'>Charlatan</a></td>
+        <td>Matthew Daley</td>
+    </tr>
+    <tr>
+        <td>Delphi</td>
+        <td><a href='https://github.com/JamieGeddes/mountebank-delphi'>mountebank-delphi</a></td>
+        <td>Jamie Geddes</td>
+    </tr>
+    <tr>
+        <td>F#</td>
+        <td><a href='https://github.com/mattherman/MbDotNet.FSharp'>MbDotNet.FSharp</a></td>
+        <td>Matthew Herman</td>
+    </tr>
+    <tr>
+        <td rowspan='2'>Go</td>
+        <td><a href='https://github.com/durmaze/gobank'>GoBank</a></td>
+        <td>Erkan</td>
+    </tr>
+    <tr>
+        <td><a href='https://github.com/senseyeio/mbgo'>mbgo</a></td>
+        <td>Senseye</td>
+    </tr>
+    <tr>
+        <td>Java</td>
+        <td><a href='https://github.com/thejamesthomas/javabank'>javabank</a></td>
+        <td>James Thomas</td>
+    </tr>
+    <tr>
+        <td>JavaScript</td>
+        <td><a href='https://www.npmjs.com/package/mountebank-helper'>mountebank-helper</a></td>
+        <td>Alex</td>
+    </tr>
+    <tr>
+        <td>Perl</td>
+        <td><a href='https://metacpan.org/release/Test-Mountebank'>Test::Mountebank</a></td>
+        <td>Dagfinn Reiersøl</td>
+    </tr>
+    <tr>
+        <td rowspan='3'>PHP</td>
+        <td><a href="https://github.com/meare/juggler">Juggler</a></td>
+        <td>Andrejs Mironovs</td>
+    </tr>
+    <tr>
+        <td><a href='https://github.com/demyan112rv/mountebank-api-php'>mountebank-api-php</a></td>
+        <td>Demyanovsky Ruslan</td>
+    </tr>
+    <tr>
+        <td><a href='https://packagist.org/packages/abevallez/mountebank-php'>mountebank-php</a></td>
+        <td>Abraham Vallez</td>
+    </tr>
+    <tr>
+        <td rowspan='5'>Python</td>
+        <td><a href='https://pypi.python.org/pypi/mountepy'>mountepy</a></td>
+        <td>Michał Bultrowicz</td>
+    </tr>
+    <tr>
+        <td><a href='https://github.com/kevinjqiu/py-mountebank'>py-mountebank</a></td>
+        <td>Kevin Qiu</td>
+    </tr>
+    <tr>
+        <td><a href='https://pypi.python.org/pypi/mountebank-python'>mountebank-python</a></td>
+        <td>Alex Holyoke</td>
+    </tr>
+    <tr>
+        <td><a href='https://pypi.org/project/mbtest'>mbtest</a></td>
+        <td>Simon Brunning</td>
+    </tr>
+    <tr>
+        <td><a href='https://pypi.org/project/mounty/'>mounty</a></td>
+        <td>Vasile Pop</td>
+    </tr>
+    <tr>
+        <td>Ruby</td>
+        <td><a href='https://github.com/CoderKungfu/mountebank-gem'>mountebank-gem</a></td>
+        <td>Michael Cheng</td>
+    </tr>
+    <tr>
+        <td>Shell</td>
+        <td><a href='https://github.com/sebero/mountebank-sh'>mountebank-sh</a></td>
+        <td>Sergi Bech Robleda</td>
+    </tr>
+    <tr>
+        <td>TypeScript</td>
+        <td><a href='https://www.npmjs.com/package/@anev/ts-mountebank'>ts-mountebank</a></td>
+        <td>Angela Evans</td>
+    </tr>
+    <tr>
+        <td>Swift</td>
+        <td><a href='https://github.com/MountebankSwift/MountebankSwift/'>MountebankSwift</a></td>
+        <td>Teameh & Mat1th</td>
+    </tr>
+</table>
+
+<h1>Persistence Stores</h1>
+
+<p>By default, mountebank stores everything in memory, which becomes a performance bottleneck
+at scale. The <a href='//docs/commandLine#start'><code>--datadir</code></a> option creates
+a local file-based data store, but the community has created (or is creating) more performant
+and robust options using first-class databases using the <code>--impostersRepository</code>
+command line option.</p>
+
+<table>
+    <tr>
+        <th>Database</th>
+        <th>Name</th>
+        <th>Author</th>
+    </tr>
+    <tr>
+        <td>Redis</td>
+        <td><a href='https://github.com/eljusto/mountebank-redis-repository'>mountebank-redis-repository</a></td>
+        <td>Boris Zhidkov</td>
+    </tr>
+    <tr>
+        <td>Mongo</td>
+        <td><a href='https://github.com/ibnc/mountebankMongo'>mountebankMongo</a></td>
+        <td>Isabelle Carter (who created the plugin capability)</td>
+    </tr>
+</table>
+
+<h1>Build Plugins</h1>
+
+<p>Since <code>mb</code> is another process to manage during your build, having a
+plugin for your build tool is handy. If you have a plugin, please add it to this page
+or let me know about it.</p>
+
+<table>
+    <tr>
+        <th>Build tool</th>
+        <th>Name</th>
+        <th>Author</th>
+    </tr>
+    <tr>
+        <td>Grunt</td>
+        <td><a href='https://github.com/mountebank-testing/mountebank-grunt'>grunt-mountebank</a></td>
+        <td>Brandon Byars</td>
+    </tr>
+    <tr>
+        <td>Gradle</td>
+        <td><a href='https://github.com/ndrwdn/mountebank-gradle'>mountebank-gradle</a></td>
+        <td>Andrew Dean</td>
+    </tr>
+    <tr>
+        <td>Maven</td>
+        <td><a href='https://github.com/thejamesthomas/mountebank-maven-plugin'>mountebank-maven-plugin</a></td>
+        <td>James Thomas</td>
+    </tr>
+</table>
+
+<h2>Build Plugin Implementation Notes</h2>
+
+<p>As of v1.4.3, <code>mb</code> writes the pidfile (mb.pid by default, although it can be overridden on the
+    command line) only after it has fully initialized, including binding to the socket and initializing any
+    imposters passed in a config file.  You can use this fact to wait for the pidfile creation before returning
+    from a build task to guarantee initialization before the next task runs.</p>
+
+<p>Also note that the command to actually run mountebank can vary depending on both the platform and the installation
+    package.  To support all options, you will need to dynamically determine the executable command to run.</p>
+
+<p>See the <a href='https://github.com/bbyars/grunt-mountebank/blob/master/tasks/mb.js'>grunt-mountebank code</a>
+    that mountebank uses for its build for an example.</p>
+
+<h1>User Interfaces</h1>
+
+<p>The following help drive mountebank through a user interface.</p>
+
+<table>
+  <tr>
+    <th>Name</th>
+    <th>Author</th>
+  </tr>
+  <tr>
+    <td><a href='http://donhenton.github.io/mountebank-UI/public_html/index.html#/'>Mountebank-UI</a></td>
+    <td>Don Henton</td>
+  </tr>
+  <tr>
+    <td><a href='https://github.com/Opus-Software/disguise'>Disguise</a></td>
+    <td>Opus Software</td>
+  </tr>
+</table>
+
+<h1>Additional tools</h1>
+
+<p>The following are higher level tools that augment mountebank with additional functionality.</p>
+
+<table>
+    <tr>
+        <th>Name</th>
+        <th>Description</th>
+        <th>Author</th>
+    </tr>
+    <tr>
+        <td><a href='https://github.com/DevTestSolutions/TestDoubles'>TestDoubles</a></td>
+        <td>Adds cluster support, named REST APIs, persisted request/response pairs, enhanced command
+            line interface (CLI), with packaging mechanisms including Node.js, Docker, Vagrant, PM2 etc</td>
+        <td>CA Technologies</td>
+    </tr>
+    <tr>
+        <td><a href='https://github.com/Tzinov15/swagger-bank'>swagger-bank</a></td>
+        <td>A library to bridge Swagger API specifications and the Mountebank Test-Double tool</td>
+        <td>Alex</td>
+    </tr>
+</table>
+
+<%- include('../_footer') -%>

package/src/views/docs/gettingStarted.ejs

@@ -0,0 +1,146 @@
+<%
+title = 'getting started'
+description = 'A getting started guide for using mountebank'
+%>
+
+<%- include('../_header') -%>
+
+<h1>Getting Started</h1>
+
+<p><b>Install:</b></p>
+
+<pre><code>npm install -g mountebank</code></pre>
+
+<p><b>Run:</b></p>
+
+<pre><code>mb</code></pre>
+
+<p><b>Alternative install methods:</b></p>
+
+<p>You can avoid a global install with <code>npm install mountebank</code>, in which
+case you can run mountebank using the <code>npx mb</code> command.</p>
+
+<p>Alternatively, you can download the Docker image and run:</p>
+
+<pre><code>docker pull bbyars/mountebank:<%= version %>
+docker run --rm -p 2525:2525 -p 4545:4545 -p 5555:5555 bbyars/mountebank:<%= version %> start </code></pre>
+
+<p><b>Use:</b></p>
+
+<p>By default, mountebank listens on port 2525, but that's not the port that your
+imposters (test doubles) will listen on.  To show a couple different kinds of
+imposters, let's create both an http imposter and a tcp one.  We'll use the
+<code>curl</code> command line tool to call mountebank's
+<a href='/docs/api/overview'>api</a>.  The following command creates the
+http imposter, listening on port 4545, by <code>POST</code>ing to
+http://localhost:2525/imposters with the given body.
+The <code>predicates</code> are optional - if you don't include any, the stub
+always matches, and the response is always sent.</p>
+
+<p class='info-icon'>The <a href='/docs/api/contracts'>contracts page</a>
+provides an easy to use exploration of the JSON structure.</p>
+
+<testScenario name='getting-started'>
+    <step type='exec'>
+<pre><code>curl -i -X POST -H 'Content-Type: application/json' http://localhost:<change to='<%= port %>'>2525</change>/imposters --data '{
+  "port": 4545,
+  "protocol": "http",
+  "stubs": [{
+    "responses": [
+      { "is": { <strong class='highlight1'>"statusCode": 400</strong> }}
+    ],
+    "predicates": [{
+      "and": [
+        {
+          "equals": {
+            "path": "/test",
+            "method": "POST",
+            "headers": { "Content-Type": "application/json" }
+          }
+        },
+        {
+          "not": {
+            "contains": { "body": "requiredField" },
+            "caseSensitive": true
+          }
+        }
+      ]
+    }]
+  }]
+}'
+</code></pre>
+    </step>
+
+<p>Let's test it out:</p>
+
+    <step type='exec'>
+<pre><code>curl -i -X POST -H 'Content-Type: application/json' http://localhost:4545/test --data '{"optionalField": true}'</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 <strong class='highlight1'>400</strong> Bad Request
+Connection: close
+Date: <volatile>Sat, 04 Jan 2014 02:48:16 GMT</volatile>
+Transfer-Encoding: chunked</code></pre>
+        </assertResponse>
+    </step>
+
+<p>Had we not tailored the request to match the predicates, we would have instead received
+the default response.  For instance, let's send a request that leaves off the Content-Type:</p>
+
+    <step type='exec'>
+<pre><code>curl -i -X POST http://localhost:4545/test --data '{"optionalField": true}'</code></pre>
+
+        <assertResponse>
+<pre><code>HTTP/1.1 200 OK
+Connection: close
+Date: <volatile>Sat, 04 Jan 2014 02:48:16 GMT</volatile>
+Transfer-Encoding: chunked</code></pre>
+        </assertResponse>
+    </step>
+
+<p>mountebank can stub binary tcp equally well, which is convenient when your application integrates
+with a downstream system using one of the myriad binary RPC
+protocols.  Those protocols tend to rely on language-specific serialization to return an object
+graph.  Your test can use the same serialization code to create a binary stream of the object you want
+the imposter to return during an RPC call, and encode it as a base64 string.  That string is what you
+send to the imposter.  In the example below, we're telling the imposter to respond with a base64-encoded
+string of "hello, world!" when a tcp request containing the string "sayHello" is sent to port 5555, which
+could correspond to the method name serialized in the RPC call:</p>
+
+    <step type='exec'>
+<pre><code>curl -i -X POST -H 'Content-Type: application/json' http://localhost:<change to='<%= port %>'>2525</change>/imposters --data '{
+  "port": 5555,
+  "protocol": "tcp",
+  "mode": "binary",
+  "stubs": [{
+    "responses": [
+      { "is": { <strong class='highlight1'>"data": "aGVsbG8sIHdvcmxkIQ=="</strong> }}
+    ],
+    "predicates": [{ "contains": { "data": "c2F5SGVsbG8=" } }]
+  }]
+}'</code></pre>
+    </step>
+
+<p>We'll use <code>nc</code> (netcat) to make the tcp request, which is like <code>telnet</code>
+but easier to script.</p>
+
+    <step type='exec'>
+<pre><code>echo "Calling sayHello over binary protocol" | nc localhost 5555</code></pre>
+
+        <assertResponse>
+<pre><code><strong class='highlight1'>hello, world!</strong></code></pre>
+        </assertResponse>
+    </step>
+
+<p>Finally, we can shut down both imposters by issuing an HTTP <code>DELETE</code> to
+both imposters, which are identified by the port number on the URL:</p>
+
+    <step type='exec'>
+<pre><code>curl -X DELETE http://localhost:<change to='<%= port %>'>2525</change>/imposters/4545
+curl -X DELETE http://localhost:<change to='<%= port %>'>2525</change>/imposters/5555</code></pre>
+    </step>
+</testScenario>
+
+<p>Explore more in the links on the left.  Don't hesitate to <a href='/support'>ask</a> for help!</p>
+
+<%- include('../_footer') -%>

package/src/views/docs/mentalModel.ejs

@@ -0,0 +1,51 @@
+<%
+title = 'mental model'
+description = 'A mental model of how mountebank works'
+%>
+
+<%- include('../_header') -%>
+
+<h1>Mental model</h1>
+
+<p><a href='https://www.manning.com/'>Manning Publishing</a> has been kind enough to help diagram
+    the following mental model, describing how mountebank works:</p>
+
+<a href='https://www.manning.com/books/testing-microservices-with-mountebank?a_aid=mb&a_bid=ee3288f4'>
+    <img alt='mental model' src='https://freecontent.manning.com/wp-content/uploads/mentalmodel-testing-microservices-with-mountebank2.png'
+  style='width: 50em' />
+</a>
+
+<h2>Lexicon</h2>
+
+<dl>
+  <dt>imposter</dt>
+  <dd>A server representing a test double.  An <em>imposter</em> is identified by a port and
+  a protocol.  mountebank is non-modal and can create as many <em>imposters</em> as your test requires.</dd>
+
+  <dt>stub</dt>
+  <dd>A set of configuration used to generate a response for an <em>imposter</em>.  An <em>imposter</em>
+  can have 0 or more <em>stubs</em>, each of which are associated with different <em>predicates</em>.</dd>
+
+  <dt>predicate</dt>
+  <dd>A condition that determines whether a given <em>stub</em> is responsible for responding.  Each
+  <em>stub</em> can have 0 or more <em>predicates</em>.</dd>
+
+  <dt>response</dt>
+  <dd>The configuration that generates the response for a <em>stub</em>.  Each <em>stub</em> can have
+  0 or more <em>responses</em>.</dd>
+
+  <dt>response type</dt>
+  <dd>Defines the specific type of configuration used to generate a response.  The simplest type is called
+  <em>is</em>, and allows you to define the <em>imposter's</em> response directly.  mountebank also
+  supports a <em>proxy</em> response type, which allows record-replay behavior, and an <em>inject</em>
+  response type, which allows you to script mountebank responses.  Each <em>response</em> has exactly
+  one <em>response type</em>.</dd>
+
+  <dt>stub behavior</dt>
+  <dd>Adds additional post-processing to a response, for example by adding latency to the
+  response or augmenting the response with more information.  A <em>response</em> can have zero
+  or more <em>behaviors</em>, which represent a pipeline of such transformations.</dd>
+
+</dl>
+
+<%- include('../_footer') -%>