Testing REST Clients with Restito

I’m excited about this new library I ran into and I would like to share the excitement. It’s called Restito, it’s on GitHub, and I actually found it on a blog from 2012, so… where were you all this time?

Restito is a Java library to mock out REST APIs. It’s self-described as the complement of REST Assured. REST Assured is also a library used for testing REST APIs (like Restito), but it mimics the client (while Restito mimics the server), it has a fluent API (like Restito), and it’s very popular (no shame in aspiring for popularity). In fact, I see REST Assured as the gold standard for testing REST APIs. Restito, on the other hand, is new to me.

Problem

What problem are we trying to solve here? We are building a service that’s chatting with a remote instance of our Jama application, using Jama’s REST API.

Inside the service there is a whole chain of classes, that are dependent on each other. There is a class JamaProxy, which has some business level methods in the context of our Jama application. It calls into JamaRestClient, which understands how to form request URLs and payloads compliant with Jama’s REST API. It uses javax.ws.rs.client.WebTarget and friends to set up the actual connection with the remote Jama application.

Concerns are separated, and when it comes to unit testing, each concern can also be unit tested separately. IntegrationHandler has a corresponding IntegrationHandlerTest, which uses a mocked version of JamaProxy. The same for JamaProxy, which uses a mocked version of JamaRestClient. But how do we unit test JamaRestClient?

JamaRestClient is strongly tied to WebTarget (in fact, its only purpose in life is transformation into and out from WebTarget); it makes no sense to abstract WebTarget out of JamaRestClient. I have tried to mock WebTarget in unit tests before, and found it notoriously hard to mock (hard meaning annoying and ugly). The way a lot of its method calls are chained (fluent API, builder pattern) doesn’t lead to very pretty unit test code. Also, mocking out a request library is scary because there are so many ways you can end up with a mock that doesn’t behave like the real thing.

It would be more realistic if we used real communication to the real REST API. It would allow us to use the real request library. Restito lets us use real communication, without the need to set up a real Jama application to talk to. (If you are going to tell me that this is not real unit testing, please talk to the hand: we have narrowed the scope of the test to the smallest unit that makes sense, and we’re doing it in a way that increases confidence in our product.)

When it comes to integration testing, you might have the same problem. Depending on how you define integration testing, it may be undesirable to create real Jama application to communicate with. Restito can help in the same way as for unit testing. It’s not a full substitute for “the real thing”, so we likely desire a system test that involves a real Jama application, but Restito will help boost confidence in earlier phases of development.

Including Restito

Restito is available as a Maven artifact, so you add it to the POM file as follows:

<dependencies>  
...  
    <dependency>  
        <groupId>com.xebialabs.restito</groupId>  
        <artifactId>restito</artifactId>  
        <version>0.8.2</version>  
        <scope>test</scope>  
    </dependency>

...

<groupId>com.xebialabs.restito</groupId>

<artifactId>restito</artifactId>

</dependency>

Your POM would also have dependencies on the client library, for example javax.ws.rs-api for WebTarget, but that’s beside the point here.

How It Works

Restito sets up a little web server, on a random available port. It is then possible to set up expectations, before exercising the test subject. Then even verifications can be done to make sure that calls to the REST API actually happened, in the way expected. Here is some example code — some non-essential constants and methods, as well as imports omitted for brevity:

public class JamaRestClientTest {  
    private StubServer server = new StubServer();  
    private ObjectMapper objectMapper = new ObjectMapper();  
  
    @Before  
    public void setUp() {  
        server.run();  
    }  
  
    @Test  
    public void testGetItem() throws JsonProcessingException {  
        Item expected = someItem(SOME_ITEM_ID);  
  
        whenHttp(server)  
                .match(get(format("/contour/rest/v1/items/%d", SOME_ITEM_ID)))  
                .then(ok(), jsonContent(expected), contentType("application/json"));  
  
        JamaRestClient subject
            = new JamaRestClient(baseUrl(), MY_USER_NAME, MY_PASSWORD, null);  
        Item actual = subject.get("items", SOME_ITEM_ID, Item.class);  
  
        assertEquals(SOME_ITEM_ID, actual.getId());  
    }  
  
    private Action jsonContent(Object object) throws JsonProcessingException {  
        return stringContent(objectMapper.writeValueAsString(object));  
    }  
  
    private String baseUrl() {  
        return format("http://localhost:%d/contour", server.getPort());  
    }  
}

public class JamaRestClientTest {

private StubServer server = new StubServer();

private ObjectMapper objectMapper = new ObjectMapper();

@Before

public void setUp() {

server.run();

}

@Test

public void testGetItem() throws JsonProcessingException {

Item expected = someItem(SOME_ITEM_ID);

whenHttp(server)

.match(get(format("/contour/rest/v1/items/%d", SOME_ITEM_ID)))

.then(ok(), jsonContent(expected), contentType("application/json"));

JamaRestClient subject

= new JamaRestClient(baseUrl(), MY_USER_NAME, MY_PASSWORD, null);

Item actual = subject.get("items", SOME_ITEM_ID, Item.class);

assertEquals(SOME_ITEM_ID, actual.getId());

}

private Action jsonContent(Object object) throws JsonProcessingException {

return stringContent(objectMapper.writeValueAsString(object));

}

private String baseUrl() {

return format("http://localhost:%d/contour", server.getPort());

}

Some things to note in the above code fragment: I have also introduced some usage of Jackson’s ObjectMapper, so that I don’t need to deal with literal JSON here, but can just pass an object in. I’ve not seen support for that in Restito, and I find that unfortunate.

The code is fairly easy to read, thanks to the fluent API of Restito, and without the need to mock out all the nested objects returned by WebTarget’s fluent API. I find it interesting how that almost sounds at odds: using a nice fluent API for a mock because fluent APIs are so hard to mock.

An example of a verification that could be added to the above example would be like this:

verifyHttp(server)  
    .once(method(Method.GET),
        parameter("documentKey", "DOC-KEY-123"),
        not(withHeader("x-some-header")));

verifyHttp(server)

.once(method(Method.GET),

parameter("documentKey", "DOC-KEY-123"),

not(withHeader("x-some-header")));

The above code fragment shows how we verify that the server actually received an HTTP GET request once, with a certain query parameter, and specifically without a header called x-some-header.

Conclusion

I observe that Restito does not have the richness and cleanness on its fluent API, as REST Assured does, which it seems to aspire to. But I’ve fallen in love with it nonetheless, because I can see the void it’s filling. I was able to create a working test with Restito in under 15 minutes from the moment I started Googling. (It actually was 14 minutes, I time myself.) I know I will be using it a lot in the future.