Debugging Issues

MockServer supports the following features to simplify debugging

Retrieve the following items:
- recorded requests
- recorded requests and responses
- active expectations
- recorded expectations
- logs
Configurable log level
Clear and simple log messages for all actions
JSON Schema validation of all requests to the REST API, with clear failure messages
Clear failure messages when verifying requests (that support "show difference" in IntelliJ)

Retrieving Recorded Requests

All requests the MockServer or the proxy receives are recorded.

It is possible to retrieve the recorded requests, as show below in the code examples.

Requests are returned in the order they are received, and which requests are returned can be filter using a request matcher.

HttpRequest[] recordedRequests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
    .retrieveRecordedRequests({})
    .then(
        function (recordedRequests) {
            console.log(JSON.stringify(recordedRequests));
        },
        function (error) {
            console.log(error);
        }
    );

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS"

HttpRequest[] recordedRequests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).retrieveRecordedRequests({
    "path": "/some/path",
    "method": "POST"
}).then(
    function (recordedRequests) {
        console.log(JSON.stringify(recordedRequests));
    },
    function (error) {
        console.log(error);
    }
);

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS" -d '{
    "path": "/some/path",
    "method": "POST"
}'

String recordedRequests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
            .withPath("/some/path")
            .withMethod("POST"),
        Format.JAVA
    );

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS&format=JAVA" -d '{
    "path": "/some/path"
}'

String recordedRequests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
            .withPath("/some/path")
            .withMethod("POST"),
        Format.JSON
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).retrieveRecordedRequests({
    "path": "/some/path",
    "method": "POST"
}).then(
    function (recordedRequests) {
        console.log(JSON.stringify(recordedRequests));
    },
    function (error) {
        console.log(error);
    }
);

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS&format=JSON" -d '{
    "path": "/some/path"
}'

Retrieve Recorded Requests & Responses

All requests the MockServer or the proxy receives are recorded.

It is possible to retrieve the recorded requests and their responses, as show below in the code examples.

Requests and responses are returned in the order they occur, and what is returned can be filter using a request matcher.

HttpRequestAndHttpResponse[] httpRequestAndHttpResponse = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequestsAndResponses(
        request()
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
    .retrieveRecordedRequestsAndResponses({})
    .then(
        function (recordedRequestsAndResponses) {
            console.log(JSON.stringify(recordedRequestsAndResponses));
        },
        function (error) {
            console.log(error);
        }
    );

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUEST_RESPONSES"

HttpRequestAndHttpResponse[] httpRequestAndHttpResponse = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequestsAndResponses(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).retrieveRecordedRequestsAndResponses({
    "path": "/some/path",
    "method": "POST"
}).then(
    function (recordedRequestsAndResponses) {
        console.log(JSON.stringify(recordedRequestsAndResponses));
    },
    function (error) {
        console.log(error);
    }
);

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUEST_RESPONSES" -d '{
    "path": "/some/path",
    "method": "POST"
}'

Retrieving Active Expectations

It is possible to retrieve the active expectations, as show below in the code examples.

Expectations are returned in the order they have been added, and which expectations are returned can be filter using a request matcher.

Expectation[] activeExpectations = new MockServerClient("localhost", 1080)
    .retrieveActiveExpectations(
        request()
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
    .retrieveActiveExpectations({})
    .then(
        function (activeExpectations) {
            console.log(JSON.stringify(activeExpectations));
        },
        function (error) {
            console.log(error);
        }
    );

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS"

Expectation[] activeExpectations = new MockServerClient("localhost", 1080)
    .retrieveActiveExpectations(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).retrieveActiveExpectations({
    "path": "/some/path",
    "method": "POST"
}).then(
    function (activeExpectations) {
        console.log(JSON.stringify(activeExpectations));
    },
    function (error) {
        console.log(error);
    }
);

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS" -d '{
    "path": "/some/path",
    "method": "POST"
}'

String activeExpectations = new MockServerClient("localhost", 1080)
    .retrieveActiveExpectations(
        request()
            .withPath("/some/path")
            .withMethod("POST"),
        Format.JAVA
    );

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS&format=JAVA" -d '{
    "path": "/some/path"
}'

String activeExpectations = new MockServerClient("localhost", 1080)
    .retrieveActiveExpectations(
        request()
            .withPath("/some/path")
            .withMethod("POST"),
        Format.JSON
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).retrieveActiveExpectations({
    "path": "/some/path",
    "method": "POST"
}).then(
    function (activeExpectations) {
        console.log(JSON.stringify(activeExpectations));
    },
    function (error) {
        console.log(error);
    }
);

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=ACTIVE_EXPECTATIONS&format=JSON" -d '{
    "path": "/some/path"
}'

Retrieving Recorded Expectations

For MockServer forward actions or all proxy requests expectations are recorded containing the request received and response returned.

It is possible to retrieve the recorded expectations, as show below in the code examples.

Expectations are returned in the order they have been recorded, and which expectations are returned can be filter using a request matcher.

Expectation[] recordedExpectations = new MockServerClient("localhost", 1080)
    .retrieveRecordedExpectations(
        request()
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
    .retrieveRecordedExpectations({})
    .then(
        function (recordedExpectations) {
            console.log(JSON.stringify(recordedExpectations));
        },
        function (error) {
            console.log(error);
        }
    );

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS"

Expectation[] recordedExpectations = new MockServerClient("localhost", 1080)
    .retrieveRecordedExpectations(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).retrieveRecordedExpectations({
    "path": "/some/path",
    "method": "POST"
}).then(
    function (recordedExpectations) {
        console.log(JSON.stringify(recordedExpectations));
    },
    function (error) {
        console.log(error);
    }
);

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS" -d '{
    "path": "/some/path",
    "method": "POST"
}'

String recordedExpectations = new MockServerClient("localhost", 1080)
    .retrieveRecordedExpectations(
        request()
            .withPath("/some/path")
            .withMethod("POST"),
        Format.JAVA
    );

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS&format=JAVA" -d '{
    "path": "/some/path"
}'

String recordedExpectations = new MockServerClient("localhost", 1080)
    .retrieveRecordedExpectations(
        request()
            .withPath("/some/path")
            .withMethod("POST"),
        Format.JSON
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080).retrieveRecordedExpectations({
    "path": "/some/path",
    "method": "POST"
}).then(
    function (recordedExpectations) {
        console.log(JSON.stringify(recordedExpectations));
    },
    function (error) {
        console.log(error);
    }
);

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=RECORDED_EXPECTATIONS&format=JSON" -d '{
    "path": "/some/path"
}'

Retrieving Recorded Logs

MockServer and the proxy record log messages for all major actions, including:

adding expectations
matching requests
executing actions (response, forward, callback & error)
returning responses
clearing logs, expectations & recorded requests
resetting logs, expectations & recorded requests

It is possible to retrieve the recorded log messages, as show below in the code examples.

Log messages are returned in the order they have been recorded, and which log messages are returned can be filter using a request matcher.

String logMessages = new MockServerClient("localhost", 1080)
    .retrieveLogMessages(
        request()
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
    .retrieveLogMessages({})
    .then(
        function (logMessages) {
            // logMessages is a String[]
            console.log(logMessages);
        },
        function (error) {
            console.log(error);
        }
    );

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=LOGS"

String logMessages = new MockServerClient("localhost", 1080)
    .retrieveLogMessages(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
    .retrieveLogMessages({
        "path": "/some/path",
        "method": "POST"
    })
    .then(
        function (logMessages) {
            // logMessages is a String[]
            console.log(logMessages);
        },
        function (error) {
            console.log(error);
        }
    );

curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=LOGS" -d '{
    "path": "/some/path",
    "method": "POST"
}'

String[] logMessages = new MockServerClient("localhost", 1080)
    .retrieveLogMessagesArray(
        request()
            .withPath("/some/path")
    );

var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
    .retrieveLogMessages({
        "path": "/some/path"
    })
    .then(
        function (logMessages) {
            // logMessages is a String[]
            console.log(logMessages);
        },
        function (error) {
            console.log(error);
        }
    );

Logging

All interactions with the MockServer are logged including setting up expectations, matching expectations, clearing expectations and verifying requests. The log can be particularly helpful when trying to debug why a test is failing or expectations are not being matched.

The following information is logged:

WARN - exceptions, errors
INFO - all interactions with the MockServer including setting up expectations, matching expectations, clearing expectations and verifying requests
TRACE - all matcher results, including when specific matchers fail (such as HeaderMatcher)

The TRACE level logging results in a lot of verbose logging but can be very helpful to debug why a complex matcher (such as the JSON Schema matcher) is not matching.

Logging with JUnit @Rule or API

MockServer uses SL4J for logging so if MockSever is being launched using the JUnit @Rule or programmatically via an API configure the logging output by configuring SLF4J

Logging with Command Line

When running MockServer directly from the command line the command line argument -logLevel can be used to set the log level, as follows:

java -jar ~/Downloads/mockserver-netty-5.7.2-jar-with-dependencies.jar -serverPort 1080 -logLevel DEBUG

Alternatively a system property mockserver.logLevel can be used to set the log level, as follows:

java -Dmockserver.logLevel=INFO -jar ~/Downloads/mockserver-netty-5.7.2-jar-with-dependencies.jar -serverPort 1080

Configuring Java Logger

When running MockServer from the command line it relies on the Java Logger java.util.logging.Logger in addition to controlling the log level of MockServer using -logLevel the underlying logging framework can be configured (overriding the default configuration) by specifying the System Property java.util.logging.config.file or java.util.logging.config.class as detailed in the LogManager JavaDoc.

An example Java Logger configuration file (which would be configured using java.util.logging.config.file) is available in github.

The default logging configuration can be overridden as follows:

java -Djava.util.logging.config.file=/path/to/example_logging_configuration.properties -jar ~/Downloads/mockserver-netty-5.7.2-jar-with-dependencies.jar -serverPort 1080 -logLevel DEBUG

Logging with Maven Plugin

The mockserver-maven-plugin provides a logLevel settings that can be used to define the log level for all MockServer classes, as follows:

 <plugin>
     <groupId>org.mock-server</groupId>
     <artifactId>mockserver-maven-plugin</artifactId>
     <version>5.7.2</version>
     <configuration>
        <serverPort>1080</serverPort>
        <logLevel>DEBUG</logLevel>
     </configuration>
     <executions>
         <execution>
             <id>process-test-classes</id>
             <phase>process-test-classes</phase>
             <goals>
                 <goal>runForked</goal>
             </goals>
         </execution>
         <execution>
             <id>verify</id>
             <phase>verify</phase>
             <goals>
                 <goal>stopForked</goal>
             </goals>
         </execution>
     </executions>
 </plugin>

Logging with npm module

When running MockServer using the mockserver-node Grunt plugin and Node.js (npm) module the verbose option can be used to enable INFO level logging and the trace option can be used to enable TRACE level logging.

It is generally recommended to enable verbose which should provide the correct amount of information, trace is only required for very low level debugging.

var mockserver = require('mockserver-node');

mockserver
    .start_mockserver({
        serverPort: 1080,
        verbose: true,
        trace: true
    })
    .then(
        function () {
            console.log("started MockServer");
        },
        function (error) {
            console.log(JSON.stringify(error));
        }
    );

Logging with Grunt plugin

When running MockServer using the mockserver-node as a Grunt plugin module the verbose option can be used to enable INFO level logging and the trace option can be used to enable TRACE level logging. The --verbose command line flag can also be used to enable the mockserver-node verbose option from the command line.

It is generally recommended to enable verbose which should provide the correct amount of information, trace is only required for very low level debugging.

grunt.initConfig({
        start_mockserver: {
            options: {
                serverPort: 1080,
                verbose: true,
                trace: true
            }
        },
        stop_mockserver: {
            options: {
                serverPort: 1080
            }
        }
});

grunt.loadNpmTasks('mockserver-node');

Disabling Logging

To disable logging the following options can be used:

-Dmockserver.logLevel=OFF - to disable logging from the MockServer and Proxy classes
-Droot.logLevel=OFF - to disable all logging from all other classes