src/views/docs/api/contracts/imposter-description.ejs
<div id='imposter-port-description'>
<p>The port to run the imposter on.<p>
<p>Optional. Defaults to a randomly assigned port that will be returned in the response</p>
<p class='warning-icon'>On Linux and Mac, requires <code>sudo</code> to set to a privileged port (1-1023)</p>
</div>
<div id='imposter-protocol-description'>
<p>Defines the protocol that the imposter will respond to. Valid values are:</p>
<ul class='bullet-list indent'>
<li><a href='/docs/protocols/http'>http</a></li>
<li><a href='/docs/protocols/https'>https</a></li>
<li><a href='/docs/protocols/tcp'>tcp</a></li>
<li><a href='/docs/protocols/smtp'>smtp</a></li>
</ul>
</div>
<div id='imposter-name-description'>
<p>Optional. Allows you to provide a descriptive name that will show up in the <a href='/logs'>logs</a>
and the <a href='/imposters'>imposters UI</a>.</p>
</div>
<div id='imposter-recordRequests-description'>
<p>Optional. If set to <code>true</code>, the server will record requests received, for mock verification purposes.</p>
</div>
<div id='imposter-numberOfRequests-description'>
<p>The number of requests to this imposter</p>
<p class='info-icon'>Set <code>recordRequests</code> to <code>true</code> on the imposter to also record
the details of each request in the <code>requests</code> array below</p>
</div>
<div id='imposter-key-description'>
<p>Optional. Allows you to pass in an SSL private key for creating an https server (this field only applies
to https). Must be a PEM-formatted string. Defaults to a built-in private key.</p>
<p class='info-icon'>More information: <a href='/docs/protocols/https'>https</a></p>
</div>
<div id='imposter-cert-description'>
<p>Optional. Allows you to pass in an SSL certificate for creating an https server (this field only applies
to https). Must be a PEM-formatted string. Defaults to a built-in self-signed certificate.</p>
<p class='info-icon'>More information: <a href='/docs/protocols/https'>https</a></p>
</div>
<div id='imposter-mutualAuth-description'>
<p>Optional. If set to <code>true</code>, the server will request a client certificate. Since the goal
is simply to virtualize a server requiring mutual auth, invalid certificates will not be rejected.</p>
<p class='info-icon'>More information: <a href='/docs/protocols/https'>https</a></p>
</div>
<div id='imposter-defaultResponse-description'>
<p>Optional. Allows you to override the default response that mountebank sends back if no predicate matches
a request. Even if a predicate does match but the response isn't fully specified, these values get merged
in to complete the response.</p>
<p class='info-icon'>More information: <a href='/docs/protocols/http'>http</a>,
<a href='/docs/protocols/https'>https</a>, and <a href='/docs/protocols/tcp'>tcp</a></p>
</div>
<div id='imposter-stubs-description'>
<p>A set of behaviors used to generate a response for an imposter. An imposter can have 0 or more stubs,
each of which are associated with different predicates and support different responses.</p>
<p>You would use multiple stubs for an imposter if the types of response you return depends on something
in the request, matched with a predicate.</p>
</div>
<div id='imposter-stubs-responses-description'>
<p>An array of responses to return for this stub. The responses array defines a circular buffer - every
time the stub is used for the request, the first response is pulled from the front of the
<code>responses</code> array, evaluated, and pushed to the back of the array. This elegantly does what
you want. In the common case, when you always want to return the same response, you just add one response
to the array. More complex scenarios will require that the same endpoint returns a sequence of
different responses for the same predicates. Simply add them all to the array in order.
When the sequence finishes, it will start over. More complexity can be added by simply
adding more responses to the array without complicating the contract.</p>
<p>Each response is defined by one and only one <i>response type</i>. This defines the type of response
generated. The following response types are supported, and described in more detail in the contract
example to the left as well as the links provided below.</p>
<ul class='bullet-list indent'>
<li><a href='/docs/api/stubs'>is</a>: A canned response</li>
<li><a href='/docs/api/proxies'>proxy</a>: A record/replay response</li>
<li><a href='/docs/api/injection'>inject</a>: A scripted response</li>
</ul>
<p class='info-icon'>More informaton: <a href='/docs/api/stubs'>stubs</a></p>
</div>
<div id='imposter-stubs-responses-is-description'>
<p>The <code>is</code> response type represents a canned response that you define. The response fields will
be those defined with each protocol according to the links below (the http response fields
are shown in this example). smtp stubbing is not supported.</p>
<p>You do not need to fill in every response field; mountebank will merge the specified response fields
with the response defaults (see the protocol pages below for the defaults).</p>
<ul class='bullet-list indent'>
<li><a href='/docs/protocols/http'>http</a></li>
<li><a href='/docs/protocols/https'>https</a></li>
<li><a href='/docs/protocols/tcp'>tcp</a></li>
</ul>
<p class='info-icon'>More information: <a href='/docs/api/stubs'>stubs</a></p>
</div>
<div id='imposter-stubs-responses-repeat-description'>
<p>Causes the response to repeat a given number of times before returning the next response
in the <code>responses</code> array.</p>
<p class='info-icon'>More information: <a href='/docs/api/stubs'>stub responses</a></p>
</div>
<div id='imposter-stubs-behaviors-description'>
<p>Behaviors alter the generated response in some way. The following behaviors are supported:</p>
<ul class='bullet-list indent'>
<li><code>wait</code> - adds latency to the response</li>
<li><code>decorate</code> - post-processes the response using a JavaScript function</li>
<li><code>shellTransform</code> - post-processes the response using a command line application</li>
<li><code>copy</code> - copies a value from the request into the response</li>
<li><code>lookup</code> - lookups values from an external data source</li>
</ul>
<p>More information: <a href='/docs/api/behaviors'>behaviors</a></p>
</div>
<div id='imposter-stubs-behaviors-wait-description'>
<p>Adds latency to a response by waiting a specified number of milliseconds before sending the response.</p>
<p class='info-icon'>More information: <a href='/docs/api/behaviors'>behaviors</a></p>
</div>
<div id='imposter-stubs-behaviors-decorate-description'>
<p>Post-processes the response before sending it. Since post-processing requires JavaScript
injection, the <code><a href='/docs/commandLine'>--allowInjection</a></code> flag must be passed.
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 dynamic data into the response, for
example. The value passed into the <code>decorate</code> behavior is a JavaScript function that
can take up to an object containing 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>
<p class='warning-icon'>JavaScript injection requires the
<a href='/docs/commandLine'>--allowInjection command line flag</a> to execute.</p>
<p class='info-icon'>More information: <a href='/docs/api/behaviors'>behaviors</a></p>
</div>
<div id='imposter-stubs-behaviors-shellTransform-description'>
<p>Post-processes the response before sending it. Unlike a <code>decorate</code>, the post-processing
occurs through a command line application, which still requires the <code><a href='/docs/commandLine'>
--allowInjection</a></code> flag to be set. The command line application will be passed the request JSON
and the response JSON through environment variables, and should write the transformed response
JSON to <code>stdout</code>.</p>
<p class='warning-icon'>Shell execution requires the
<a href='/docs/commandLine'>--allowInjection command line flag</a> to execute.</p>
<p class='info-icon'>More information: <a href='/docs/api/behaviors'>behaviors</a></p>
</div>
<div id='imposter-stubs-behaviors-copy-description'>
<p>Post-processes the response by replacing the given tokens with values from the specified request fields.
You can select the appropriate values from the request using regular expressions, xpath, or jsonpath.</p>
<p class='info-icon'>More information: <a href='/docs/api/behaviors'>behaviors</a></p>
</div>
<div id='imposter-stubs-behaviors-lookup-description'>
<p>Post-processes the response by looking up data from an external data source using a key
selected from the request. The given tokens in the response are replaced with the looked up values.
You can select the appropriate keys from the request using regular expressions, xpath, or jsonpath.</p>
<p class='info-icon'>More information: <a href='/docs/api/behaviors'>behaviors</a></p>
</div>
<div id='imposter-stubs-responses-proxy-description'>
<p>The response is generated by proxying the request to a different server. You can configure mountebank
to return the saved response on subsequent requests based on certain conditions within the request.</p>
<p class='info-icon'>More information: <a href='/docs/api/proxies'>proxies</a></p>
</div>
<div id='imposter-stubs-responses-proxy-to-description'>
<p>Represents the destination to send the request. This should be a URL with the protocol and
host but without a path (as shown to the left). http and https imposters can both proxy to
http and https. tcp proxies can only proxy to tcp (e.g. tcp://someserver:3000).</p>
<p class='info-icon'>More information: <a href='/docs/api/proxies'>proxies</a></p>
</div>
<div id='imposter-stubs-responses-proxy-mode-description'>
<p>Defines the replay behavior of the proxy. Proxy responses work by creating new elements in the
<code>stubs</code> array. This field determines whether that newly created stub will be before or
after the current stub in the array. There are two options:</p>
<ul class='bullet-list indent'>
<li><code>proxyOnce</code> - always records the proxied call in the <code>stubs</code> array in
front of itself, so the same call is never proxied twice.</li>
<li><code>proxyAlways</code> - saves the proxied call <em>after</em> itself in the <code>stubs</code>
array. This allows you to capture different responses for the same call.
You can later replay <code>proxyAlways</code> stubs by issuing a <code>GET</code>
or <code>DELETE</code> to the imposter with the <code>removeProxies</code> and
<code>replayable</code> query params, and re-<code>POST</code>ing the imposter.</li>
</ul>
<p class='info-icon'>More information: <a href='/docs/api/proxies'>proxies</a></p>
</div>
<div id='imposter-stubs-responses-proxy-key-description'>
<p>In situations where the destination expects to use SSL mutual authentication, it will request a client
certificate. This field can contain the PEM-formatted client private key.</p>
<p class='info-icon'>More information: <a href='/docs/api/proxies'>proxies</a></p>
</div>
<div id='imposter-stubs-responses-proxy-cert-description'>
<p>In situations where the destination expects to use SSL mutual authentication, it will request a client
certificate. This field can contain the PEM-formatted client certificate.</p>
<p class='info-icon'>More information: <a href='/docs/api/proxies'>proxies</a></p>
</div>
<div id='imposter-stubs-responses-proxy-ciphers-description'>
<p>In nearly all cases, you'll never need to use this field. However if you need to proxy to an
older HTTPS server using insecure ciphers that are no longer used, you can override the
cipher using one of the <a href='https://nodejs.org/api/tls.html#tls_modifying_the_default_tls_cipher_suite'>standard formats</a>.</p>
<p class='info-icon'>More information: <a href='/docs/api/proxies'>proxies</a></p>
</div>
<div id='imposter-stubs-responses-proxy-secureProtocol-description'>
<p>A legacy mechanism to select the TLS protocol to use. Learn more at the
<a href='https://nodejs.org/api/tls.html#tls_tls_connect_options_callback'>node documentation</a>.</p>
<p class='info-icon'>More information: <a href='/docs/api/proxies'>proxies</a></p>
</div>
<div id='imposter-stubs-responses-proxy-passphrase-description'>
<p>The shared passphrase for a private key</p>
<p class='info-icon'>More information: <a href='/docs/api/proxies'>proxies</a></p>
</div>
<div id='imposter-stubs-responses-proxy-addWaitBehavior-description'>
<p>When this field is true, mountebank will add latency to the saved responses that mirrors the time
the actual proxied call took. This is useful in load testing when you want to virtualize downstream services
but keep the latency of those services.</p>
<p class='info-icon'>More information: <a href='/docs/api/proxies'>proxies</a> and the
<a href='/docs/api/behaviors#behavior-wait'>wait behavior</a></p>
</div>
<div id='imposter-stubs-responses-proxy-addDecorateBehavior-description'>
<p>When present, adds the given function as a <code>decorate</code> behavior to each newly created response.</p>
<p class='warning-icon'>JavaScript injection requires the
<a href='/docs/commandLine'>--allowInjection command line flag</a> to execute.</p>
<p class='info-icon'>More information: <a href='/docs/api/proxies'>proxies</a></p>
</div>
<div id='imposter-stubs-responses-proxy-injectHeaders-description'>
<p>Allows you to add or override headers returned from the proxy.</p>
<p class='info-icon'>More information: <a href='/docs/api/proxies'>proxies</a></p>
</div>
<div id='imposter-stubs-responses-proxy-predicateGenerators-description'>
<p>An array of objects that defines how the predicates for new stubs are created. Proxy responses work
by creating new elements in the <code>stubs</code> array, either before the current stub (if
<code>mode</code> is <code>proxyOnce</code>) or after the current stub (if <code>mode</code> is
<code>proxyAlways</code>). Each element in the <code>predicateGenerators</code> array
will create a single element in the <code>predicates</code> array for newly created stub.</p>
<p>Each generator should contain a <code>matches</code> field containing all the request elements you
want to create predicates for. You can configure the newly created predicate with standard predicate
parameters. The created predicates will be generally be <code>deepEquals</code> predicates.</p>
<p>Alternatively, if you need more fine-grained control, you can use an <code>inject</code> field
containing a JavaScript function to create the predicates.</p>
<p class='info-icon'>More information: <a href='/docs/api/proxies'>proxies</a></p>
</div>
<div id='imposter-stubs-responses-inject-description'>
<p>mountebank is scriptable, which allows you to use JavaScript to craft the response you want in situations
where canned responses and proxy responses are not sufficient. The injected function takes four parameters
as shown on the left:</p>
<ul class='bullet-list indent'>
<li><code>request</code> - the protocol-specific request object</li>
<li><code>state</code> - initially an empty object, the same instance will be passed into every response
injection function within the same imposter. You can use it to add any cross-response state you need to save.</li>
<li><code>logger</code> - mountebank's logger, with standard <code>debug</code>, <code>info</code>,
<code>warn</code>, and <code>error</code> functions</li>
<li><code>callback</code> - For asynchronous use only, execute (with the response as a parameter) to return</li>
</ul>
<p>Injection can by synchronous or asnychronous. Simply return a value representing the response for synchronous
execution. For asynchronous execution, pass the response object into the <code>callback</code> function.</p>
<p class='warning-icon'>JavaScript injection requires the
<a href='/docs/commandLine'>--allowInjection command line flag</a> to execute.</p>
<p class='info-icon'>More information: <a href='/docs/api/injection'>injection</a></p>
</div>
<div id='imposter-stubs-predicates-description'>
<p>In the absence of a predicate, a stub always matches, and there's never a reason to
add more than one stub to an imposter. Predicates allow imposters to have much richer
behavior by defining whether or not a stub matches a request. When multiple stubs are
created on an imposter, the first stub that matches is selected.</p>
<p>Each predicate object contains one or more of the request fields as keys. Predicates
are added to a stub in an array, and all predicates are AND'd together. The following
predicate operators are allowed:</p>
<ul class='bullet-list indent'>
<li><code>equals</code> - The request field matches the predicate</li>
<li><code>deepEquals</code> - Performs nested set equality on the request field, useful when
the request field is an object (e.g. the <code>query</code> field in http)</li>
<li><code>contains</code> - The request field contains the predicate</li>
<li><code>startsWith</code> - The request field starts with the predicate</li>
<li><code>endsWith</code> - The request field ends with the predicate</li>
<li><code>matches</code> - The request field matches the JavaScript regular expression defined
with the predicate.</li>
<li><code>exists</code> - If <code>true</code>, the request field must exist. If <code>false</code>,
the request field must not exist.</li>
<li><code>not</code> - Inverts a predicate</li>
<li><code>or</code> - Logically or's two predicates together</li>
<li><code>and</code> - Logically and's two predicates together</li>
<li><code>inject</code> - Injects JavaScript to decide whether the request matches or not.</li>
</ul>
<p class='info-icon'>More information: <a href='/docs/api/predicates'>predicates</a></p>
</div>
<div id='imposter-stubs-predicates-0-equals-description'>
<p>A type of predicate that requires the given request fields to equal the predicate value.
By default, mountebank uses a case-insensitive equality.</p>
<p class='info-icon'>More information: <a href='/docs/api/predicates'>predicates</a></p>
</div>
<div id='imposter-stubs-predicates-0-caseSensitive-description'>
<p>If true, mountebank will require the request field to satisfy the predicate value in
a case sensitive comparison.</p>
<p class='info-icon'>More information: <a href='/docs/api/predicates'>predicates</a></p>
</div>
<div id='imposter-stubs-predicates-0-except-description'>
<p>Defines a regular expression that is stripped out of the request field before matching.</p>
<p class='info-icon'>More information: <a href='/docs/api/predicates'>predicates</a></p>
</div>
<div id='imposter-stubs-predicates-0-jsonpath-description'>
<p>It is common to want to use predicates on JSON response bodies, but annoying to treat the JSON as
simple text with many of the predicates. mountebank uses the <code>json</code> predicate parameter
to narrow the scope of the predicate value to a value matched by the json selector.</p>
<p class='info-icon'>More information: <a href='/docs/api/jsonpath'>jsonpath</a></p>
</div>
<div id='imposter-stubs-predicates-0-xpath-description'>
<p>It is common to want to use predicates on XML response bodies, but annoying to treat the XML as
simple text with many of the predicates. mountebank uses the <code>xpath</code> predicate parameter
to narrow the scope of the predicate value to a value matched by the xpath selector.</p>
<p class='info-icon'>More information: <a href='/docs/api/xpath'>xpath</a></p>
</div>
<div id='imposter-stubs-predicates-1-inject-description'>
<p>When none of the built-in predicates are sufficient, mountebank allows you to script the
predicate. The injected function accepts the following parameters:</p>
<ul class='bullet-list indent'>
<li><code>request</code> - the full request object</li>
<li><code>logger</code> - mountebank's logger, with standard <code>debug</code>, <code>info</code>,
<code>warn</code>, and <code>error</code> functions</li>
</ul>
<p>Return <code>true</code> to pass the predicate.</p>
<p class='warning-icon'>JavaScript injection requires the
<a href='/docs/commandLine'>--allowInjection command line flag</a> to execute.</p>
<p class='info-icon'>More information: <a href='/docs/api/injection'>injection</a></p>
</div>
<div id='imposter-stubs-matches-description' class='response'>
<p>An array of all activity by this stub, useful in troubleshooting why a stub is or is not
responding (generally for debugging your predicates). Each object will contain the incoming
<code>request></code>, the outgoing <code>response</code>, and a <code>timestamp</code>.</p>
<p class='warning-icon'>The <code>matches</code> array only shows up in the response if the
<a href='/docs/commandLine'><code>--debug command line parameter</code></a> is passed.</p>
</div>
<div id='imposter-endOfRequestResolver-description'>
<p>The tricky bit about using the raw TCP protocol is knowing when a request ends. Application
protocols give some way of determining this, such as the <code>Content-Length</code> header in
HTTP or by embedding the message length in binary protocols. By default, mountebank assumes
each packet represents a separate request, which typically limits the size of each request
to somewhere between 1500 and 64k bytes (you'll get a larger payload using the loopback interface
on localhost, but lower level protocols like Ethernet will force a smaller payload over the network).
This strategy works for many scenarios as simple serialized requests tend to fall below this size,
but breaks down with large requests.</p>
<p>mountebank allows you the flexibility to determine when a request ends using the
<code>endOfRequestResolver</code> at the imposter level. The value is a JavaScript function
that takes a parameter that represents all request data captured from all packets so far. If the
imposter is in <code>text</code> mode, the parameter will be a string; in binary it will be a
<a href='http://nodejs.org/api/buffer.html'>node.js Buffer object</a>.
mountebank's <code>logger</code> object is also passed as an optional second parameter to
assist in troubleshooting.</p>
<p class='warning-icon'>JavaScript injection requires the
<a href='/docs/commandLine'>--allowInjection command line flag</a> to execute.</p>
<p class='info-icon'>More information: <a href='/docs/protocols/tcp'>tcp</a></p>
</div>
<div id='imposter-requests-description' class='response'>
<p>mountebank will save off all requests to the imposter for mock verification. By retrieving
the imposter, your client code can determine if an expected service call was in fact made.</p>
<p class='info-icon'>More information: <a href='/docs/api/mocks'>mocks</a></p>
</div>
<div id='imposter-_links-description' class='response'>
<p>Defines the hypermedia relationships for the imposter.</p>
</div>