MockServer Proxy has the following clients:

Note: It is not necessary to use the provided clients because the protocol is very simple JSON/HTTP web api.

All clients support:

  • verifying which requests have been recorded
  • retrieving all recorded requests / responses as JSON or Expectation objects
  • outputting to the log all recorded requests / responses as Expectations in JSON format
  • outputting to the log all recorded requests / responses as Expectations in Java code format that can be pasted into test setup methods
  • clearing recorded requests / responses (selectively)
  • resetting (clearing all recorded requests / responses)
 

Java Proxy Client

To simplest way to interact with proxy from Java is to use org.mockserver.client.proxy.ProxyClient which provides the following API:

public class ProxyClient {

    /**
     * Start the client communicating to the proxy at the specified host and port
     * for example:
     *   ProxyClient mockServerClient = new ProxyClient("localhost", 1080);
     *
     * @param host the host for the proxy to communicate with
     * @param port the port for the proxy to communicate with
     */
    public ProxyClient(String host, int port);

    /**
     * Pretty-print the json for all requests / responses as Expectations to the log.
     * They are printed into a dedicated log called mockserver_request.log
     */
    public ProxyClient dumpToLogAsJSON();

    /**
     * Pretty-print the json for matching requests and their responses as Expectations to the log.
     * They are printed into a dedicated log called mockserver_request.log
     *
     * @param httpRequest the http request that is matched against when deciding what to log if null all requests are logged
     */
    public ProxyClient dumpToLogAsJSON(HttpRequest httpRequest);

    /**
     * Output Java code for creating all requests / responses as Expectations to the log.
     * They are printed into a dedicated log called mockserver_request.log
     */
    public ProxyClient dumpToLogAsJava();

    /**
     * Output Java code for creating matching requests and their responses as Expectations to the log.
     * They are printed into a dedicated log called mockserver_request.log
     *
     * @param httpRequest the http request that is matched against when deciding what to log if null all requests are logged
     */
    public ProxyClient dumpToLogAsJava(HttpRequest httpRequest);

    /**
     * Reset the proxy by clearing recorded requests
     */
    public ProxyClient reset();

    /**
     * Stop the proxy gracefully (only support for Netty and Vert.X versions, not supported for WAR version)
     */
    public ProxyClient stop();

    /**
     * Clear all recorded requests that match the httpRequest parameter
     *
     * @param httpRequest the http request that is matched against when deciding whether to clear recorded requests
     */
    public ProxyClient clear(HttpRequest httpRequest);

    /**
     * Verify a request has been sent for example:
     *
     *   mockServerClient
     *           .verify(
     *                   request()
     *                           .withPath("/some_path")
     *                           .withBody("some_request_body")
     *           );
     *
     * @param httpRequest the http request that must be matched for this verification to pass
     * @throws AssertionError if the request has not been found
     */
    public ProxyClient verify(HttpRequest httpRequest); throws AssertionError

    /**
     * Verify a request has been sent for example:
     *
     *   mockServerClient
     *           .verify(
     *                   request()
     *                           .withPath("/some_path")
     *                           .withBody("some_request_body"),
     *                   VerificationTimes.exactly(3)
     *           );
     *
     * Times supports multiple static factory methods:
     *
     *   once()      - verify the request was only received once
     *   exactly(n)  - verify the request was only received exactly n times
     *   atLeast(n)  - verify the request was only received at least n times
     *
     * @param httpRequest the http request that must be matched for this verification to pass
     * @param times       the number of times this request must be matched
     * @throws AssertionError if the request has not been found
     */
    public ProxyClient verify(HttpRequest httpRequest, Times times); throws AssertionError

    /**
     * Retrieve the recorded requests that match the httpRequest parameter as expectations, use null for the parameter to retrieve all requests
     *
     * @param httpRequest the http request that is matched against when deciding whether to return each expectation, use null for the parameter to retrieve for all requests
     * @return an array of all expectations that have been recorded by the proxy
     */
    public Expectation[] retrieveAsExpectations(HttpRequest httpRequest);

    /**
     * Retrieve the recorded requests that match the httpRequest parameter as a JSON array, use null for the parameter to retrieve all requests
     *
     * @param httpRequest the http request that is matched against when deciding whether to return each expectation, use null for the parameter to retrieve for all requests
     * @return a JSON array of all expectations that have been recorded by the proxy
     */
    public String retrieveAsJSON(HttpRequest httpRequest);
}
 

JavaScript Proxy Client

To interact with the proxy from JavaScript it is possible to use either:

To include this file is an HTML page use one of the following script tag to load the file from MaxCDN:

<script type="text/javascript" src="https://cdn.rawgit.com/jamesdbloom/mockserver/63e0a42396431720505d9f5730427c8a7f6de972/mockserver-client-javascript/src/main/javascript/proxyClient.js"></script>

To use the Node.js module add the following code to your node project:

var mockServer = require('mockserver-client'),
    proxyClient = mockServer.proxyClient;

Both versions of proxyClient provide the same API as follows:

var proxyClient = function (host, port) {
    "use strict";

    /**
     * Retrieve the recorded requests that match the httpRequest parameter as a JSON array, use null for the parameter to retrieve all requests
     *
     * @param request the http request that is matched against when deciding whether to return each expectation, use null for the parameter to retrieve for all requests
     * @param a JSON array of all expectations that have been recorded by the proxy
     */
    var retrieve = function (request),

    /**
     * Verify a request has been sent for example:
     *
     *   client.verify({
     *       'httpRequest': {
     *           'method': 'POST',
     *           'path': '/somePath'
     *       }
     *   }, 2, true);
     *
     * @param request the http request that must be matched for this verification to pass
     * @param count   the number of times this request must be matched
     * @param exact   true if the count is matched as "equal to" or false if the count is matched as "greater than or equal to"
     * @throws an error is the verify fails detailing which requests have been sent
     */
    verify = function (request, count, exact),

    /**
     * Verify a sequence of requests has been sent for example:
     *
     *   client.verifySequence(
     *       {
     *          'method': 'POST',
     *          'path': '/first_request'
     *       },
     *       {
     *          'method': 'POST',
     *          'path': '/second_request'
     *       },
     *       {
     *          'method': 'POST',
     *          'path': '/third_request'
     *       }
     *   );
     *
     * @param arguments the list of http requests that must be matched for this verification to pass
     * @throws an error is the verify fails detailing which requests have been sent
     */
    verifySequence = function (),

    /**
     * Reset the proxy by clearing all recorded requests
     */
    reset = function (),

    /**
     * Clear all recorded requests that match the specified path
     *
     * @param path the path to decide which expectations to cleared
     */
    clear = function (path),

    /**
     * Pretty-print the json for all requests / responses that match the specified path
     * as Expectations to the log. They are printed into a dedicated log called mockserver_request.log
     *
     * @param path the path to decide which expectations to dump to the log
     */
    dumpToLogs = function (path);

    return {
        retrieve: retrieve,
        verify: verify,
        reset: reset,
        clear: clear,
        dumpToLogs: dumpToLogs
    };
};
 

Ruby MockServer Proxy Client  Gem Version

To interact with MockServer Proxy from Ruby use mockserver-client gem as follows:

Add the gem to the application Gemfile:

gem 'mockserver-client'

Or install the gem directly:

gem install mockserver-client

To write recorded requests to the logs as Java:

require "mockserver-client"

class SomeClass

  include MockServer
  include MockServer::Model::DSL

  def writeToLogAsJava
    ProxyClient.new('localhost', 1090).dump_log(request(:POST, '/login'), true)
  end

end

To write recorded requests to the logs as JSON:

require "mockserver-client"

class SomeClass

  include MockServer
  include MockServer::Model::DSL

  def writeToLogAsJSON
    ProxyClient.new('localhost', 1090).dump_log(request(:POST, '/login'))
  end

end

To verify a request has been sent:

require "mockserver-client"

class SomeClass

  include MockServer
  include MockServer::Model::DSL

  def verifyRequest
    client = ProxyClient.new('localhost', 1090)
    client.verify(request(:POST, '/login') do |request|
        request.body = exact({ username: 'foo', password: 'bar' }.to_json)
        request.cookies = [cookie("sessionId", ".*")]
    end)
  end

end