How to Setup Stub Server Easily Using Moco

1. Introduction

It’s almost impossible to underestimate the importance of testing during software development. And if we’re talking about testing, it’s hard to ignore mocking tools that often play an essential role in ensuring robust coverage.

This article explores Moco, a versatile and lightweight mocking tool that simplifies mock servers for various protocols.

We’ll explore Moco’s features and how to get started, as well as look at practical examples to illustrate its capabilities.

2. What’s Moco?

Moco is an open-source mocking library that allows us to stub and mock services. It’s lightweight and extremely simple to use and configure.

Moco supports multiple protocols, such as HTTP, HTTPS, and socket, making it an excellent choice for testing different types of applications, from web services to real-time communication apps.

3. Getting Started With Moco

One of Moco’s main advantages is its ease of setup and use. Integrating it into a new project or an existing one is pretty straightforward.

3.1. JSON Configuration and Standalone Server

Before diving into the code, it’s worth noting that Moco allows us to write configurations using JSON and run them standalone. It’s beneficial for quick setups without any coding.

Here is a simple example of a JSON config we can write in the config.json file:

[
  {
    "request": {
      "uri": "/hello"
    },
    "response": {
      "text": "Hello, Moco!"
    }
  }
]

To start the server using this configuration, we run the moco-runner:

java -jar moco-runner-1.5.0-standalone.jar http -p 12345 -c config.json

This command runs an HTTP server on port 12345 using the provided config.json. The mock will be available at http://localhost:12345/hello.

These standalone setups provide a lot of flexibility and receive the same level of developer support as code configurations.

3.2. Set Up

To start using Moco with Maven, we’ll include this dependency:

<dependency>
    <groupId>com.github.dreamhead</groupId>
    <artifactId>moco-runner</artifactId>
    <version>1.5.0</version>
    <scope>test</scope>
</dependency>

For Gradle projects, we need to use this:

testImplementation 'com.github.dreamhead:moco-runner:1.5.0'

4. Practical Examples With Java

Moco has a rich Java API, which gives us a lot of freedom in defining our mock resources. But for now, let’s check how the server initialization works with some simple examples.

4.1. Server Initialization

We must understand how to set up servers based on the protocol to initialize a Moco server using Java. Here’s a quick overview:

HttpServer server = Moco.httpServer(12345); // Initialize server on port 12345 
server.request(Moco.by(Moco.uri("/hello")))
  .response(Moco.text("Hello, Moco!")); // Set up a basic response
 
Runner runner = Runner.runner(server); 
runner.start(); // Start the server

In this example, we first initialize an HTTP server on port 12345. Then, we configure the server to respond with “Hello, Moco!” whenever it requests the /hello endpoint. Finally, we start the server using Runner’s start() method.

Also, we shouldn’t forget to stop the server after we’re done:

runner.stop();

For example, in tests, we can put it into the method with the @AfterEach annotation. For HTTPS, we need to create a certificate first, which is represented by the HttpsCertificate object, and then use httpsServer() method:

HttpsCertificate certificate = certificate(pathResource("certificate.jks"), 
  "keystorePassword", "certPassword");
HttpsServer server = httpsServer(12346, certificate);

If we want to use socket connection, Moco provides socketServer():

final SocketServer server = socketServer(12347);

We can also use JSON configurations we mentioned before during the server creation:

final HttpServer server = jsonHttpServer(12345, file("config.json"));

4.2. HTTP Codes and Responses

Now that we have the basic setup, let’s explore more complex examples. Let’s return a JSON response:

server.request(by(uri("/api/user")))
  .response(header("Content-Type", "application/json"))
  .response(json("{\"id\": 1, \"name\": \"Ryland Grace\", \"email\": \"[email protected]\"}"));

If we store our JSON in a file, we can provide its path:

server.request(by(uri("/api/user")))
  .response(header("Content-Type", "application/json"))
  .response(Moco.file("src/test/resources/user.json"));

The default HTTP code for Moco’s response is 200. But it allows us to change it, for example, to reproduce error responses:

server.request(Moco.match(Moco.uri("/unknown"))).response(Moco.status(404), Moco.text("Not Found"));

Also, in the examples above, we didn’t specify the HTTP method, which means the GET was used. To mock a POST request, we can use post() instead of request(). In fact, in the previous example, we could have explicitly used get().

Let’s see a POST mock example:

server.post(by(uri("/resource"))).response("resource updated");

Moco has separate get(), post(), put(), and delete() methods for the GET, POST, PUT, and DELETE.

Additionally, we can specify the content for the Moco to check against:

server.request(json(file("user.json"))).response("resource updated");

4.3. More Fine Tuning

The examples above only scratch the surface of Moco’s potential. In fact, Moco allows us to fine-tune our server in numerous ways. For example, we can configure query parameters, cookies, various media types, custom conditions, and many more for expected requests.

In this example, we’re matching requests using JSONPath:

server.request(eq(jsonPath("$.item[*].price"), "0")).response("we have free item");

When configuring response, we can emulate proxy, redirect, file attachments, change response latency, return it in the cycle, etc. For instance, to simulate a resource that changes state over time, we can configure a mock server to return different responses for each sequential request:

// First request will get "Alice", second and third will get "Bob" and "Clyde". Forth request will return "Alice" again.
server.request(by(uri("/user"))).response(seq("Alice", "Bob", "Clyde")); 

5. Using Moco in Unit Tests

Moco integrates seamlessly with JUnit. We can effectively mock external services by embedding the Moco server within the test lifecycle. Here’s a simple example of how we can do it:

public class MocoUnitTest {
    private Runner runner;

    @BeforeEach
    public void setup() {
        HttpServer server = Moco.httpServer(12345);
        server.request(Moco.by(Moco.uri("/test"))).response("Test response");
        runner = Runner.runner(server);
        runner.start();
    }

    @AfterEach
    public void tearDown() {
        runner.stop();
    }

    // Our tests
}

In the setup, we create an HTTP server that responds to requests at /test with “Test response“. We start this server before each test and stop it afterward.

Now, let’s try to test our server:

@Test
void givenMocoHttpServer_whenClientSendsRequest_thenShouldReturnExpectedResponse() throws Exception {
    HttpClient client = HttpClient.newHttpClient();
    HttpRequest request = HttpRequest.newBuilder()
      .uri(URI.create("http://localhost:12345/test"))
      .build();
    
    HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
    assertEquals("Test response", response.body());
}

In this example, we use Java’s built-in HttpClient to send HTTP requests to our Moco server. This approach avoids additional dependencies, making it an excellent choice for testing HTTP interactions in our unit tests.

5.1. Using With @Rule

Moco uses TestRule in JUnit 4 to simplify integration. The MocoJunitRunner provides several ways to run a Moco server as a TestRule, which starts the server before our test and stops it after the test:

public class MocoJunitHttpUnitTest {
    private static final HttpServer server = httpServer(12306);

    static {
        server.response(text("JUnit 4 Response"));
    }

    @Rule
    public MocoJunitRunner runner = MocoJunitRunner.httpRunner(server);

    @Test
    public void givenMocoServer_whenClientSendsRequest_thenShouldReturnExpectedResponse() throws IOException, InterruptedException {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
          .uri(URI.create("http://localhost:12306"))
          .build();

        HttpResponse<String> response = client
          .send(request, HttpResponse.BodyHandlers.ofString());

        assertEquals(response.body(), "JUnit 4 Response");
    }
}

@ExtendWith(MocoExtension.class)
@MocoHttpServer(filepath = "src/test/resources/foo.json", port = 12345)  // Load JSON config from file system
public class MocoHttpTest {
    @Test
    public void givenMocoServer_whenClientSendsRequest_thenShouldReturnExpectedResponse() throws IOException, InterruptedException {
        HttpClient client = HttpClient.newHttpClient();
        HttpRequest request = HttpRequest.newBuilder()
          .uri(URI.create("http://localhost:12345/hello"))
          .build();

        HttpResponse<String> response = client
          .send(request, HttpResponse.BodyHandlers.ofString());

        assertEquals("Hello, Moco!", response.body());
    }
}

HttpServer server = httpServer(12345, log()); // we can also specify file for log output as a String parameter in log()