Debugging Issues

MockServer supports the following features to simplify debugging

• Configurable log level
• Clear and simple log messages for all actions
• Clear failure messages when verifying requests (that support "show difference" in IntelliJ)
• Ability to dump all configured expectations to the log

In addition MockServer has simple and straight forward code that can be easily debugged manually when the logs don't provide enough information to determine why something is behaving as expected.

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 and expectation dump when mockServerClient.dumpToLog() is called
• 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.

When MockServer is run from the command line, Maven plugin, Grunt plugin or npm module the log is written to a file called mockserver.log in the current working directory where the MockServer is running.

Logging with JUnit @Rule or API

If the MockSever is being launched using the JUnit @Rule or programmatically via an API then a custom logback configuration file to override the default MockServer or MockServer Proxy logging settings. An example logback configuration file is available in github.

A custom logback configuration file can be specified using the logback.configurationFile system property with an absolute or relative file path or a classpath, as follows: -Dlogback.configurationFile=example_logback.xml

A custom logback configuration file will also be automatically picked up if it is called logback.xml and is in the root of the classpath, however, the jar-with-dependencies already contains a logback.xml file, so to override this, the overriding logback.xml file must be higher (i.e. earlier) in the classpath.

Logging with Command Line

When running MockServer directly from the command line the system property mockserver.logLevel can be used to set the log level, as follows:

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

It is also possible to specify a custom logback configuration file to override the default MockServer or MockServer Proxy logging settings. An example logback configuration file is available in github.

A custom logback configuration file can be specified using the logback.configurationFile system property with an absolute or relative file path or a classpath, as follows:

java -Droot.logLevel=WARN -Dmockserver.logLevel=INFO -Dlogback.configurationFile=example_logback.xml -jar ~/Downloads/mockserver-netty-3.12-jar-with-dependencies.jar -serverPort 1080 -proxyPort 1090

A custom logback configuration file will also be automatically picked up if it is called logback.xml and is in the root of the classpath, however, the jar-with-dependencies already contains a logback.xml file, so to override this, the overriding logback.xml file must be higher (i.e. earlier) in the classpath.

Logging with Maven Plugin

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

 <plugin>
     <groupId>org.mock-server</groupId>
     <artifactId>mockserver-maven-plugin</artifactId>
     <version>3.12</version>
     <configuration>
        <serverPort>1080</serverPort>
        <proxyPort>1090</proxyPort>
        <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 Grunt plugin or npm module

When running MockServer using the mockserver-grunt 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. In addition the --verbose command line flag can be used for Grunt builds to enable the mockserver-grunt verbose option dynamically.

Disabling Logging

To disable logging the following options can be used:

• -Dmockserver.logLevel=OFF - to disable logging from the MockServer and MockServer Proxy classes
• -Droot.logLevel=OFF - to disable all logging from all other classes (i.e. all none MockServer and MockServer Proxy classes)

If logging is disabled then no log file will be created. This is because the log files are only created when the first item is written to the log file.

Dumping Expectations To Log

To simplify debugging MockServer expectations can be dumped to the log at WARN level using pretty-printed JSON.

To dump all expectations to the log use dumpToLog as follows:

Java

new MockServerClient("localhost", 1080).dumpToLog()

JavaScript

mockServerClient("localhost", 1080).dumpToLogs();

Ruby

client = MockServerClient.new('localhost', 1080)
client.dump_log()

To dump only specific expectations to the log use dumpToLog as follows:

Java

new MockServerClient("localhost", 1080).dumpToLog(
        request()
                .withMethod("GET")
                .withPath("/somePath")
);

JavaScript

mockServerClient("localhost", 1080).dumpToLogs('/somePath');

Ruby

client = MockServerClient.new('localhost', 1080)
client.dump_log(request(:GET, '/somePath'))

Debugging Java Code

To further understand why an exception is not being matched it is possible to debug the MockServer java code, in the following classes:

• org.mockserver.mockserver.MockServerHandler - main entry point for handling requests in for all versions of MockServer except the deployable WAR
• org.mockserver.server.MockServerServlet - main entry point for handling requests in the deployable WAR
• org.mockserver.matchers.HttpRequestMatcher - main class that orchestrates request matching
• org.mockserver.mock.MockServerMatcher - main class that orchestrates expectation, including matching, ttl, times and returning correct action

Debugging JUnit @Rule or API

Debugging when using the JUnit @Rule or API should be as simple as running your test in debug.

Debugging Command Line

Debugging a remote JVM (i.e. when running MockServer from the command line) typically requires providing the -agentlib:jdwp command line switch, as follows:

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005 -jar ~/Downloads/mockserver-netty-3.12-jar-with-dependencies.jar -serverPort 1080 -proxyPort 1090

Debugging Maven Plugin

Maven can be debugged using mvnDebug which using a debug port of 8000, as follows:

mvnDebug test

mvnDebug runs the JVM using the following additional settings: -Xdebug -Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=8000

If you are using the surefire plugin to run your tests you can debug your tests using the surefire plugin debug options, as follows:

mvn -Dmaven.surefire.debug test

If you are using the failsafe plugin to run your tests you can debug your tests using the failsafe plugin debug options, as follows:

mvn -Dmaven.failsafe.debug verify

Debugging Grunt plugin or npm module

To debug the Grunt plugin or npm module you need to provide the javaDebugPort option. This option will enable the following command line switch '-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=' + options.javaDebugPort.

For example debug node module, as follows:

var mockserver = require('mockserver-grunt');
mockserver.start_mockserver({
                serverPort: 1080,
                proxyPort: 1090,
                javaDebugPort: 5005
            });

// do something

mockserver.stop_mockserver();

For example debug Grunt plugin, as follows:

grunt.initConfig({
    start_mockserver: {
        start: {
            options: {
                serverPort: 1080,
                proxyPort: 1090,
                javaDebugPort: 5005
            }
        }
    },
    stop_mockserver: {
        stop: {

        }
    }
});

grunt.loadNpmTasks('mockserver-grunt');