9531add Dec 24, 2017
4 contributors

Users who have contributed to this file

@dreamhead @htynkn @seabornlee @treppo
260 lines (189 sloc) 6.89 KB


You have several ways to use Moco. One is API, which you can use in your unit test. The other is that run Moco as standalone. Currently, you put all your configuration in JSON file.

On the other hand, Moco has several different ways to integrate with some tools: Maven plugin, Gradle plugin and shell support.

Table of Contents



Moco has been published on Maven repository, so you can refer to it directly in your dependency. This is core dependency


A gradle example is as follow:

repositories {

dependencies {

API example

Here is an typical Moco test case in JUnit.

import org.junit.Test;
import com.github.dreamhead.moco.HttpServer;
import org.apache.http.client.fluent.Content;
import org.apache.http.client.fluent.Request;
import com.github.dreamhead.moco.Runnable;

import static com.github.dreamhead.moco.Moco.*;
import static com.github.dreamhead.moco.Runner.*;
import static;
import static org.junit.Assert.assertThat;

public void should_response_as_expected() throws Exception {
    HttpServer server = httpServer(12306);

    running(server, new Runnable() {
        public void run() throws IOException {
            Content content = Request.Get("http://localhost:12306").execute().returnContent();
            assertThat(content.asString(), is("foo"));

As shown above, we created a new server and configure it as expected. And then run our test against this server.

Here, We use Apache Http Client Fluent API to request our testing server.

Runner API

You may need to control server start/stop by yourself, for example, in your Before (or setup) method, runner API could be used.

import org.junit.After;
import org.junit.Before;
import org.junit.Test;


import static com.github.dreamhead.moco.Moco.httpServer;
import static com.github.dreamhead.moco.Runner.runner;
import static;
import static org.junit.Assert.assertThat;

public class MocoRunnerTest {
    private Runner runner;

    public void setup() {
        HttpServer server = httpServer(12306);
        runner = runner(server);

    public void tearDown() {

    public void should_response_as_expected() throws IOException {
        Content content = Request.Get("http://localhost:12306").execute().returnContent();
        assertThat(content.asString(), is("foo"));


Moco can be used as standalone to run with configuration and you can download standalone directly: Standalone Moco Runner

First of all, a JSON configuration file needs to be provided to start Moco.

    "response" :
        "text" : "foo"


It's time to run Moco standalone server:

java -jar moco-runner-<version>-standalone.jar http -p 12306 -c foo.json

Now, open your browser and input "http://localhost:12306". You will see "foo". That's it.

JSON configuration in Java API

@Since 0.10.0

If you have setup your server with JSON configuration, you can also your configuration from Java API.

import static com.github.dreamhead.moco.Moco.file;
import static com.github.dreamhead.moco.Moco.pathResource;
import static com.github.dreamhead.moco.MocoJsonRunner.jsonHttpServer;
import static com.github.dreamhead.moco.Runner.running;
import static com.github.dreamhead.moco.helper.RemoteTestUtils.port;
import static com.github.dreamhead.moco.helper.RemoteTestUtils.root;
import static;
import static org.junit.Assert.assertThat;

public class MocoJsonHttpRunnerTest extends AbstractMocoStandaloneTest {
    public void should_return_expected_response() throws Exception {
        final HttpServer server = jsonHttpServer(12306, file("foo.json"));
        running(server, new Runnable() {
            public void run() throws Exception {
                Content content = Request.Get("http://localhost:12306").execute().returnContent();
                assertThat(content.asString(), is("foo"));


HTTPS is also a mainstream usage for HTTP protocol. Moco supports HTTPS as well. The main difference in API is that a certificate is required for HTTPS. On the other hand, httpsServer should be used.

final HttpsCertificate certificate = certificate(pathResource("cert.jks"), "mocohttps", "mocohttps");
final HttpsServer server = httpsServer(certificate, hit);

If you want to use HTTPS for standalone server. certificate information could be provided as CLI arguments.

java -jar moco-runner-<version>-standalone.jar https -p 12306 -c foo.json --https /path/to/cert.jks --cert mocohttps --keystore mocohttps


Socket is a common integration channel. There is only content available in socket.

final SocketServer server = socketServer(12306);

You can also use socket in standalone server.

java -jar moco-runner-<version>-standalone.jar socket -p 12306 -c foo.json

More socket APIs can be found here.

JUnit Integration

@Since 0.11.0

Moco provides JUnit integration to simplify the use of Moco in JUnit.

More details can be found in here.

Maven Plugin

Moco also can be used as Maven plugin.

Gradle Plugin

Moco can be used in Gradle


If you are using Mac or Linux, you may try the following approach:

  • Make sure you have JDK 6 or later.
  • Download the script.
  • Place it on your $PATH. (~/bin is a good choice if it is on your path.)
  • Set it to be executable. (chmod 755 ~/bin/moco)

Now, you can try

moco http -p 12306 -c foo.json

It will download the latest moco automatically if you don't have locally.


Scala fans can find Scala wrapper in