<p>The node module can be used to start and stop MockServer as a node module or as a Grunt plugin.</p>

<p>You may install this plugin / node module with the following command:</p>

<pre><code class="code">npm install mockserver-node --save-dev</code></pre>

<p><strong>Node Module</strong></p>

<p>To start or stop the MockServer from any Node.js code you need to import this module using <span class="inline_code">require(<span class="string_literal">'mockserver-node'</span>)</span> as follows:</p>

<pre><code class="code">var mockserver = require(<span class="string_literal">'mockserver-node'</span>);</code></pre>

<p>Then you can use either the <span class="inline_code">start_mockserver</span> or <span class="inline_code">stop_mockserver</span> functions as follows:</p>

<pre><code class="code">var mockserver = require(<span class="string_literal">'mockserver-node'</span>);
mockserver.start_mockserver({
                serverPort: <span class="numeric_literal">1080</span>,
                verbose: <span class="keyword">true</span>,
                trace: <span class="keyword">true</span>
            });

<span class="comment">// do something</span>

mockserver.stop_mockserver({
                serverPort: <span class="numeric_literal">1080</span>
            });</code></pre>

<p>You can customize the JVM arguments and set <a href="/mock_server/configuration_properties.html">configuration</a> options as follows</p>

<pre><code class="code">var mockserver = require(<span class="string_literal">'mockserver-node'</span>);
mockserver.start_mockserver({
              serverPort: <span class="numeric_literal">1080</span>,
              jvmOptions: [
                  <span class="string_literal">'-Dmockserver.enableCORSForAllResponses=true'</span>,
                  <span class="string_literal">'-Dmockserver.corsAllowMethods="CONNECT, DELETE, GET, HEAD, OPTIONS, POST, PUT, PATCH, TRACE"'</span>,
                  <span class="string_literal">'-Dmockserver.corsAllowHeaders="Allow, Content-Encoding, Content-Length, Content-Type, ETag, Expires, Last-Modified, Location, Server, Vary, Authorization"'</span>,
                  <span class="string_literal">'-Dmockserver.corsAllowCredentials=true'</span>
                  <span class="string_literal">'-Dmockserver.corsMaxAgeInSeconds=300'</span>
              ],
              mockServerVersion: <span class="string_literal">"{{ site.mockserver_version }}"</span>,
              verbose: <span class="keyword">true</span>
          });</code></pre>


<p>MockServer uses port unification to support HTTP, HTTPS, SOCKS, HTTP CONNECT, Port Forwarding Proxying on the same port. A client can then connect to the single port with both HTTP and HTTPS as the socket will automatically detected SSL traffic and decrypt it when required.</p>

<p><strong>Grunt Plugin</strong></p>

<p>If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins.</p>

<p>In your project's Gruntfile, add a section named <span class="inline_code">start_mockserver</span> and <span class="inline_code">stop_mockserver</span> to the data object passed into <span class="inline_code">grunt.initConfig()</span>.</p>

<p>The following example will result in a both a MockServer being started on ports <strong>1080</strong> and <strong>1080</strong>.</p>

<pre><code class="code">grunt.initConfig({
    start_mockserver: {
        start: {
            options: {
                serverPort: <span class="numeric_literal">1080</span>,
                trace: <span class="keyword">true</span>
            }
        }
    },
    stop_mockserver: {
        stop: {
            options: {
                serverPort: <span class="numeric_literal">1080</span>
            }
        }
    }
});

grunt.loadNpmTasks(<span class="string_literal">'mockserver-node'</span>);</code></pre>

<p><strong>Request Log</strong></p>

The request log will only be captured in MockServer if the log level is <span class="inline_code">INFO</span> (or more verbose, i.e. <span class="inline_code">DEBUG</span> or <span class="inline_code">TRACE</span>) therefore to capture the request log and use the <span class="inline_code">/retrieve</span> endpoint ensure either the option <span class="inline_code">trace: <span class="keyword">true</span></span> or the command line switch <span class="inline_code">--verbose</span> is set.

<p><strong>Grunt Plugin & NPM Module Options</strong></p>

<p><span class="inline_code"><strong>options.serverPort</strong></span></p>

<p><strong>Type:</strong> Integer <strong>Default:</strong> undefined</p>

<p>The HTTP, HTTPS, SOCKS and HTTP CONNECT port(s) for both mocking and proxying requests. Port unification is used to support all protocols for proxying and mocking on the same port(s). Supports comma separated list for binding to multiple ports.</p>

<p><span class="inline_code"><strong>options.proxyRemotePort</strong></span></p>

<p><strong>Type:</strong> Integer <strong>Default:</strong> undefined</p>

<p>Optionally enables port forwarding mode. When specified all requests received will be forwarded to the specified port, unless they match an expectation.</p>

<p><span class="inline_code"><strong>options.proxyRemoteHost</strong></span></p>

<p><strong>Type:</strong> String <strong>Default:</strong> undefined</p>

<p>Specified the host to forward all proxy requests to when port forwarding mode has been enabled using the <span class="inline_code">proxyRemotePort</span> option. This setting is ignored unless <span class="inline_code">proxyRemotePort</span> has been specified. If no value is provided for <span class="inline_code">proxyRemoteHost</span> when <span class="inline_code">proxyRemotePort</span> has been specified, <span class="inline_code">proxyRemoteHost</span> will default to <span class="inline_code"><span class="string_literal">"localhost"</span></span>.</p>

<p><span class="inline_code"><strong>options.artifactoryHost</strong></span></p>

<p><strong>Type:</strong> String <strong>Default:</strong> oss.sonatype.org</p>

<p>This value specifies the name of the artifact repository host.</p>

<p><span class="inline_code"><strong>options.artifactoryPath</strong></span></p>

<p><strong>Type:</strong> String <strong>Default:</strong> /content/repositories/releases/org/mock-server/mockserver-netty/</p>

<p>This value specifies the path to the artifactory leading to the mockserver-netty jar with dependencies.</p>

<p><span class="inline_code"><strong>options.mockServerVersion</strong></span></p>

<p><strong>Type:</strong> String <strong>Default:</strong> {{ site.mockserver_version }}</p>

<p>This value specifies the artifact version of MockServer to download.</p>

<p><strong>Note:</strong> It is also possible to specify a SNAPSHOT version to get the latest unreleased changes.</p>

<p><span class="inline_code"><strong>options.verbose</strong></span></p>

<p><strong>Type:</strong> Boolean <strong>Default:</strong> false</p>

<p>This value indicates whether the MockServer logs should be written to the console. In addition to logging additional output from the grunt task this options also sets the logging level of the MockServer to INFO. At INFO level all interactions with the MockServer including setting up expectations, matching expectations, clearing expectations and verifying requests are written to the log.</p>

<p><strong>Note:</strong> It is also possible to use the <span class="inline_code">--verbose</span> command line switch to enabled verbose level logging from the command line.</p>

<p><span class="inline_code"><strong>options.trace</strong></span></p>

<p><strong>Type:</strong> Boolean <strong>Default:</strong> false</p>

<p>This value sets the logging level of the MockServer to TRACE. At TRACE level (in addition to INFO level information) all matcher results, including when specific matchers fail (such as HeaderMatcher) are written to the log.</p>

<p><span class="inline_code"><strong>options.javaDebugPort</strong></span></p>

<p><strong>Type:</strong> Integer <strong>Default:</strong> undefined</p>

<p>This value indicates whether Java debugging should be enabled and if so which port the debugger should listen on. When this options is provided the following additional option is passed to the JVM:</p>

<pre><code class="code"><span class="string_literal">"-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address="</span> + javaDebugPort</code></pre>

<p><strong>Note:</strong> <span class="inline_code">suspend=y</span> is used so the MockServer will pause until the debugger is attached. The grunt task will wait 50 seconds for the debugger to be attached before it exits with a failure status.</p>

<p><span class="inline_code"><strong>options.jvmOptions</strong></span></p>

<p><strong>Type:</strong> String <strong>Default:</strong> undefined</p>

<p>This value allows any system properties to be passed to the JVM that runs MockServer, for example:</p>

<pre><code class="code">start_mockserver: {
    options: {
        serverPort: <span class="numeric_literal">1080</span>,
        jvmOptions: <span class="string_literal">"-Dmockserver.enableCORSForAllResponses=true"</span>
    }
}</code></pre>

<p><span class="inline_code"><strong>options.startupRetries</strong></span></p>

<p><strong>Type:</strong> Integer <strong>Default:</strong> if javaDebugPort is not set 110, but if javaDebugPort is set 500</p>

<p>This value indicates the how many times we will call the check to confirm if the mock server started up correctly. It will default to 110 which will take about 11 seconds to complete, this is normally long enough for the server to startup. The server can take longer to start up if Java debugging is enabled so this will default to 500. The default will, in some cases, need to be overridden as the JVM may take longer to start up on some architectures,  e.g. Mac seems to take a little longer.</p>
