Scott Leberknight's Weblog

In the previous blog, I showed using MockWebServer (part of OkHttp) to test HTTP client code. The test code was pretty clean and simple, but there are a few minor annoyances:

1. The boilerplate invocation to get the URI of the MockWebServer
2. Having to deal with InterruptedException using takeRequest
3. Needing to assert that the RecordedRequest returned from takeRequest is not null
4. Wrapping the assertions on a RecordedRequest in assertAll versus having an AssertJ-style fluent API

I fully admit these are all minor. However, the more I used MockWebServer the more I wanted to:

1. Reduce boilerplate code
2. Not need to deal with InterruptedException in tests
3. Not have to null-check the RecordedRequest
4. Have a fluent assertion API for RecordedRequest

In addition, there's another "gotcha" which is that if you use the no-argument takeRequest() method, your tests might never end. From the Javadoc, the takeRequest() method "will block until the request is available, possibly forever". (emphasis mine). It actually happened to me a few times before I actually read the Javadocs! After that I decided to only use the takeRequest method that accepts a timeout. This fixes the "never ends" problem. But whichever of the takeRequest methods you use, they both throw InterruptedException which you need to handle (unless you are using Kotlin in which case you don't need to worry about it).

To resolve the above "problems" I added several test utilities to kiwi-test in release 3.5.0 last July:

• MockWebServers
• MockWebServerAssertions
• RecordedRequests
• RecordedRequestAssertions

MockWebServers

This currently contains only two overloaded methods named uri. These are convenience methods to get the URI for a MockWebServer, either with or without a path. For example, instead of:

this.baseUri = server.url("/math").uri();

you can do this:

this.baseUri = MockWebServers.uri(server, "/math");

And with a static import for MockWebServers, the code is even shorter.

Is this small amount of boilerplate really worth these methods? Maybe, maybe not. Once I had written similar code a few dozen times, I decided it was worth having methods that accomplished the same thing.

Generally, I use these methods in @BeforeEach methods and store the value in a field, so that all tests can easily access it. Sometimes you don't need to store it in a field, but instead just pass it to the HTTP client:

var baseUri = MockWebServers.uri(server, "/math");
this.mathClient = new MathApiClient(client, baseUri);

In this example, the mathClient is stored in a field and each test uses it.

MockWebServerAssertions

This class is a starting point for assertions on a MockWebServer. It contains a few static factory methods to start from, one named assertThat and one named assertThatMockWebServer. The reason for the second one is to avoid conflicts with AssertJ's Assertions#assertThat methods. It provides a way to assert the number of requests made to the MockWebServer and has several other methods to assert on RecordedRequest. For example, assuming you use a static import:

assertThatMockWebServer(server)
        .hasRequestCount(1)
        .recordedRequest()
        .isGET()
        .hasPath("/status");

This code verifies that exactly one request was made, then uses the recordedRequest() method to get the RecordedRequest, and finally makes assertions that the request was a GET with path /status.

If you want to verify more than one request, you can use the hasRecordedRequest. The following code verifies that there were two requests made, and checks each one in the Consumer that is passed to hasRecordedRequest:

var path1 = "...";
var path2 = "...";
var requestBody = "{ ... }";

assertThatMockWebServer(server)
        .hasRequestCount(2)
        .hasRecordedRequest(recordedRequest1 -> {
            assertThat(recordedRequest1.getMethod()).isEqualTo("GET");
            assertThat(recordedRequest1.getPath()).isEqualTo(path1);
        })
        .hasRecordedRequest(recordedRequest2 -> {
            assertThat(recordedRequest2.getMethod()).isEqualTo("POST");
            assertThat(recordedRequest2.getPath()).isEqualTo(path2);
            assertThat(recordedRequest2.getBody().readUtf8()).isEqualTo(requestBody);
        });

RecordedRequests

While MockWebServers and MockWebServerAssertions are useful, RecordedRequests and RecordedRequestAssertions (discussed below) are the tools I use most when writing HTTP client tests.

RecordedRequests contains several methods to get a RecordedRequest from a MockWebServer. The method to use depends on whether there must be a request, or whether there may or may not be a request. If a request is required, you can use takeRequiredRequest:

var recordedRequest = takeRequiredRequest(server);

// make assertions on the RecordedRequest instance

But if it's possible that there might not be a request, you can use either takeRequestOrEmpty or takeRequestOrNull. The former returns Optional<RecordedRequest> while the latter returns a (possibly null) RecordedRequest. For example, if some business logic makes a request but only when certain requirements are met, a test can use one of these two methods:

// work with an Optional<RecordedRequest>
var maybeRequest = takeRequestOrEmpty(server);
assertThat(maybeRequest).isEmpty();

// or with a RecordedRequest directly
var request = takeRequestOrNull(server);
assertThat(request).isNull();

But wait, there's more. Not much, but there is another method assertNoMoreRequests that does what you expect: it verifies the MockWebServer does not contain any additional requests. So, once you have checked one or more requests, you can call it to verify the client didn't do anything else unexpected:

// get and assert one or more RecordedRequest

// now, verify there weren't any additional requests
assertNoMoreRequests(server);

As mentioned in the introduction, the RecordedRequest#takeRequest() method blocks, possibly forever. RecordedRequests avoids this problem by assuming all requests should already have been made by the time you want to get a request and make assertions on it.

Under the hood, all RecordedRequests methods call takeRequest(timeout: Long, unit: TimeUnit) (it's Kotlin, so the argument name is first and the type is second) and only wait 10 milliseconds before giving up. They handle InterruptedException by catching it, re-interrupting the current thread, and throwing an UncheckedInterruptedException (from the kiwi library). This allows for cleaner test code without needing to catch InterruptedException or declare a throws clause. So, your test code can just do this without worrying about timeouts:

var recordedRequest = RecordedRequests.takeRequiredRequest(server);

RecordedRequestAssertions

You use the methods in RecordedRequests to get one or more RecordedRequest to make assertions on. You can use RecordedRequestAssertions to make these assertions in a fluent-style API like AssertJ. If you don't like the AssertJ assertion chaining style, you can skip this section and move on with life. But if you like AssertJ, read on.

RecordedRequestAssertions contains several static methods to start from, and a number of assertion methods to check things like the request method, path, URI, and body. For example, suppose you are using the "Math API" from the previous blog and want to test addition. You can do this:

assertThatRecordedRequest(recordedRequest)
        .isGET()
        .hasPath("/math/add/40/2")
        .hasNoBody();

Here you are checking that a GET request was made to the server with path /math/add/40/2, and that there was no request body (since GET requests should in general not have one).

You can also verify the request body. Suppose you have a "User API" to perform various actions. To test a request sent to the "Create User" endpoint, you can write a test like this:

@Test
void shouldCreateUser() {
    var id = RandomGenerator.getDefault().nextLong(1, 501);
    var responseEntity = User.newWithRedactedPassword(id, "s_white", "Shaun White");

    server.enqueue(new MockResponse()
            .setResponseCode(201)
            .setHeader(HttpHeaders.CONTENT_TYPE, "application/json")
            .setHeader(HttpHeaders.LOCATION, UriBuilder.fromUri(baseUri).path("/users/{id}").build(id))
            .setBody(JSON_HELPER.toJson(responseEntity)));

    var newUser = new User(null, "s_white", "snowboarding", "Shaun White");
    var createdUser = apiClient.create(newUser);

    assertAll(
            () -> assertThat(createdUser.id()).isEqualTo(id),
            () -> assertThat(createdUser.username()).isEqualTo("s_white"),
            () -> assertThat(createdUser.password()).isEqualTo(User.REDACTED_PASSWORD)
    );

    var recordedRequest = RecordedRequests.takeRequiredRequest(server);

    assertThatRecordedRequest(recordedRequest)
            .isPOST()
            .hasHeader("Accept", "application/json")
            .hasPath("/users")
            .hasBody(JSON_HELPER.toJson(newUser));
            
    RecordedRequests.assertNoMoreRequests(server);
}

This test does the following:

1. Create a sample User entity
2. Set up the response that the MockWebServer should return
3. Call the create method on the "User API" client
4. Make some assertions on the returned User object
5. Get the recorded request from MockWebServer
6. Check the request
7. Verify that there are no more requests

To check the request, we verify that the request was a POST to /users, that it contains the required Accept header, and that it has the expected body. If the API is using JSON, then instead of doing the Object-to-JSON conversion manually, you can use hasJsonBodyWithEntity:

assertThatRecordedRequest(recordedRequest)
        .isPOST()
        .hasHeader("Accept", "application/json")
        .hasPath("/users")
        .hasJsonBodyWithEntity(newUser);

This will use a default kiwi JsonHelper instance. If you need control over the JSON serializaiton, you can use one of the overloaded hasJsonBodyWithEntity methods which accept either JsonHelper or a Jackson ObjectMapper. For example:

ObjectMapper mapper = customObjectMapper();

assertThatRecordedRequest(recordedRequest)
        .isPOST()
        .hasHeader("Accept", "application/json")
        .hasPath("/users")
        .hasJsonBodyWithEntity(newUser, mapper);

There are various other methods in RecordedRequestAssertions as well, for example methods to check the TLS version or whether there is a failure, perhaps because the inbound request was truncated. But the assertions in the above examples handle most of the use cases I've needed when writing HTTP client tests.

Wrapping Up

The kiwi-test library contains test utilities for making HTTP client testing with MockWebServer just a bit less tedious, with a little less boilerplate, and provides AssertJ-style fluent assertions for RecordedRequest. You can use these utilities to write cleaner and less "boilerplate-y" tests.