An Introduction to Wiremock

This post provides a brief introduction to Wiremock, showing how it can be used to to quickly and easily mock remote API calls. We'll use Wiremock to write some integration tests for a simple Dropwizard app and show you how it can be put to use in a real world scenario.

Why would I need to mock external API calls? 

There are a number of scenarios where it makes sense to mock an external API rather than call a live service.
  • The external API may still be in development and not yet available for integration. In this instance as long as a data contract has been defined (e.g. Swagger spec, WSDL), the remote API can be stubbed based on the data contract. Stubbed endpoints allows a team to continue development even when external APIs isn't fully implemented.
  • You may have little or no control over the external API uptime in development or test.  As a result you cannot guarantee it will be available to call when running integration tests. In this instance it makes sense to use mocked responses so that your tests don't fail because an external dependency is down. This is especially important if integration tests are being run as part of your Continuous Integration pipeline.  
  • You may want to test fault tolerance scenarios that aren't particularly easy to produce in a live API.  You may want the API to behave badly, but in a very specific way, in order to test how your application deals with a remote failure. Remote calls timing out is an example of a fault tolerance scenario that isn't that easy to set up on a live API. Using a mocked responses allows you to easily test a variety of failure scenarios and ensure your application behaves as expected. 

How does it work? 

Wiremock uses a Jetty Servlet container to expose HTTP endpoints that can be configured to behave in a specific way. Stubbed endpoints are configured to return any HTTP response code, header and body, allowing you to test a wide variety of integration scenarios. Even though stubbed responses are being returned, from the client applications perspective the remote calls appear authentic. As a result the client behaves in exactly the same way it would integrating with a live API.
Wiremock can be deployed as a standalone server, returning mocked responses for preconfigured endpoints. It can also be started and stopped on the fly as part of an integration test suit. This is the approach we're going to take in this post. I like the idea of being able to start the server, configure a stubbed response, run an integration test and then tear down the stub when we're done.  

Sample Code

The sample code is a small Dropwizard app that exposes a single endpoint. An integration test will call the test endpoint, triggering a remote API call which will be serviced by a Wiremock stub.  
  

Customer Resource

The CustomerResource class is a Jersey managed resource that exposes a simple endpoint. In the constructor we pass the external API URL and configure the Client that will be used for the remote call.
On line 22 the Customer that was sent to the endpoint is used to issue a HTTP POST to the credit check API. A CreditCheckResult JSON response is expected from the API, which is then returned to the client.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
@Path("/customer")
public class CustomerResource {

    private String creditCheckServerUrl;
    private Client client;
 
    public CustomerResource(String creditCheckServerUrl) {
     
        this.creditCheckServerUrl = creditCheckServerUrl; 
        client = ClientBuilder.newClient();
        client.property(ClientProperties.CONNECT_TIMEOUT, 1000);
        client.property(ClientProperties.READ_TIMEOUT,    3000);
    }
    
    @POST
    @Path("/perform-customer-credit-check")
    @Produces(MediaType.APPLICATION_JSON)
    @Consumes({MediaType.APPLICATION_JSON})
    public Response performCustomerCreditCheck(Customer customer) throws Exception {
     
        WebTarget webTarget = client.target(creditCheckServerUrl + "/credit-check-api");      
        Response response = webTarget.request().post(Entity.entity(customer, MediaType.APPLICATION_JSON));
     
        if(response.getStatus() == 200){
            return Response.ok(response.readEntity(CreditCheckResult.class), MediaType.APPLICATION_JSON).build();      
        }
     
        throw new CreditCheckFailedException("Error occurred calling Check Service");
    }
}
Figure 1.0 - customer credit check endpoint

Another component worth mentioning is ApplicationExceptionMapper. This class is used to translate application exceptions into HTTP responses. If a SocketTimeoutException is thrown a 503 Service Unavailable is returned along with a message to say the credit check service call timed out. We'll see this in action later with a fault tolerance integration test. Other exception types result in a 500 Internal Server Error and a generic error message.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
@Provider
public class ApplicationExceptionMapper implements ExceptionMapper<Throwable>
{  
    @Override
    public Response toResponse(Throwable exception)
    {          
     if(exception.getCause() instanceof SocketTimeoutException){
      return Response.status(Response.Status.SERVICE_UNAVAILABLE).
                      entity("Credit Check Service Timed Out").
                      type(MediaType.APPLICATION_JSON).build();
     }
     else{
      return Response.status(Response.Status.INTERNAL_SERVER_ERROR).
                      entity("Error occurred calling Check Service").
                      type(MediaType.APPLICATION_JSON).build();      
     }      
    }
}

                                                                             Figure 1.1 - exception mapper


Integration Test Configuration

To see Wiremock in action we're going to create 3 integration tests, all of which will call the performCustomerCreditCheck endpoint defined above. Before any tests can be written we need to do some general configuration.
  • DropWizardAppRule starts the Dropwizard application before tests are run and stops it again after they finish. This is handy as it saves us having to manually start and stop the server each time we want to run our tests.
  • WireMockRule starts a Jetty container so that Wiremock can serve the mock HTTP responses defined in our tests. Jetty is started on the port specified in the WireMockRule constructor. 
  • Client object is used to call the Jersey endpoint.
  • ObjectMapper is used to serialize/deserialize JSON. 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
public class CustomerResourceTest {

 @ClassRule    
 public static final DropwizardAppRule<WireMockDemoAppConfig> RULE = 
                 new DropwizardAppRule<WireMockDemoAppConfig>(WireMockDemoApp.class, 
                    ResourceHelpers.resourceFilePath("config.yml"));
 @Rule
 public WireMockRule wireMockRule = new WireMockRule(8090);
 
 private Client client = ClientBuilder.newClient();;     
 private ObjectMapper mapper = new ObjectMapper();


Test 1 - Credit Check Success

Lets start with a happy path test that expects a successful response from the credit check API.  Lines 4 to 10 configure a stub that will expose an endpoint at /credit-check-api . The stub expects a HTTP POST request with an application/json content type and a request body containing Customer JSON. If WireMock receives a request matching this criteria it will return a HTTP 200, an application/json content type and a response body containing the supplied CreditCheckResponse JSON. Note that the getCustomerJson and getCreditCheckResult methods are local helper methods used to build mock JSON for the expected request and response.
 
Now that a stub has been configured for the remote API call, we can call the endpoint we created earlier at /customer/perform-customer-credit-check. On line 13 we do a HTTP POST with a request body containing Customer json.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
    @Test
    public void testCustomerCreditCheckSuccessResponse() throws Exception {

     stubFor(post(urlEqualTo("/credit-check-api"))
                .withHeader("Content-Type", WireMock.equalTo("application/json"))
                .withRequestBody(WireMock.equalTo(getCustomerJson()))
                .willReturn(aResponse()
                    .withStatus(200)
                    .withHeader("Content-Type", "application/json")
                    .withBody(getCreditCheckJson())));
         
     WebTarget webTarget = client.target("http://localhost:8080/customer/perform-customer-credit-check");     Response response = webTarget.request(MediaType.APPLICATION_JSON).
                                  post(Entity.entity(getCustomer(), MediaType.APPLICATION_JSON));
     
     assertThat(response.getStatus(), equalTo(200));     
     assertThat(response.readEntity(CreditCheckResult.class), equalTo(getCreditCheckResult()));
    }

Lets quickly revisit the endpoint we created earlier (figure 1.0 above). The HTTP POST on line 13 above will be handled by the performCustomerCreditCheck endpoint. This endpoint will then make a call out to the credit check API (figure 1.0 line 8), which we configured above as a Wiremock stub. The stub will return a CreditCheckResult response and a HTTP 200, resulting in a similar response being returned by performCustomerCreditCheck.

Test 2 - Credit Check Failure

Next we'll look at a failure scenario that expects an error response from the credit check API. This time the Wiremock stub is configured to return a HTTP 503, testing how our endpoint handles an error response from the remote API.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
    @Test
    public void testCustomerCreditCheckErrorResponse() throws Exception {

     stubFor(post(urlEqualTo("/credit-check-api")).withHeader("Content-Type", WireMock.equalTo("application/json"))
                .withRequestBody(WireMock.equalTo(getCustomerJson()))
                .willReturn(aResponse()
                    .withStatus(503)
                    .withHeader("Content-Type", "application/json")));
                    
     WebTarget webTarget = client.target("http://localhost:8080/customer/perform-customer-credit-check");     Response response = webTarget.request(MediaType.APPLICATION_JSON).
                                  post(Entity.entity(getCustomer(), MediaType.APPLICATION_JSON));
     
     assertThat(response.getStatus(), equalTo(500));     
     assertThat(response.readEntity(String.class), equalTo("Error occurred calling Check Service"));
    }

This test sends a HTTP POST to /customer/perform-customer-credit-check, which results in an external call out to the credit check API (figure 1.0 line 8). The stub will return a HTTP 503 which will result in the endpoint throwing a CreditCheckFailedException. The ApplicationExceptionMapper defined earlier (Figure 1.1) will translate the CreditCheckFailedException into a HTTP 500 response which is returned to the client.

Test 3 - Credit Check Service Timeout

Our final test will look at a fault tolerance scenario. The Wiremock stub is configured to return a successful HTTP 200, but this time the response is delayed by 6 seconds. This simulates a slow or unresponsive API call and allows us to test how our application handles such a scenario. It's good practice to terminate external calls if the remote endpoint does not response within a reasonable period.
In the CustomerResource defined earlier (figure 1.0) we configured the Client with a read time out of 3 seconds. This means that if the credit check API doesn't respond within 3 seconds the call will time out and fail. The stub configuration below tests this behaviour by mocking the endpoint to wait 6 seconds before responding, more than enough time for the client application to time out.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
@Test
    public void testCustomerCreditCheckServiceTimeout() throws Exception {

     int creditCheckServiceDelayMillis = 6000;
     
     stubFor(post(urlEqualTo("/credit-check-api"))                .withHeader("Content-Type", WireMock.equalTo("application/json"))
                .withRequestBody(WireMock.equalTo(getCustomerJson()))
                .willReturn(WireMock.aResponse()
                    .withStatus(200)
                    .withHeader("Content-Type", "application/json")                    
                    .withBody(getCreditCheckJson())
                    .withFixedDelay(creditCheckServiceDelayMillis)));
     
     WebTarget webTarget = client.target("http://localhost:8080/customer/perform-customer-credit-check");     
     long startMillis = DateTime.now().getMillis();
     Response response = webTarget.request(MediaType.APPLICATION_JSON).
              post(Entity.entity(getCustomer(), MediaType.APPLICATION_JSON));
     long endMillis = DateTime.now().getMillis();
     
     assertThat((int)(endMillis - startMillis), is(lessThan(creditCheckServiceDelayMillis)));     
     assertThat(response.getStatus(), equalTo(503));
     assertThat(response.readEntity(String.class), equalTo("Credit Check Service Timed Out"));
    }

This test sends a HTTP POST to /customer/perform-customer-credit-check, which results in an external call out to the credit check API (figure 1.0 line 8). The stub will hang for 6 seconds causing the Client to time out and throw a SocketTimeOutException. The ApplicationExceptionMapper defined earlier (Figure 1.1) will translate the SocketTimeOutException into a HTTP 503 response and include a message saying that the credit check service timed out.

Running the Tests

To see the sample code in action you'll need to pull it down and run it as follows.
  • git clone https://github.com/briansjavablog/wiremock-demo.git
  • cd wiremock-demo
  • mvn test 

What else can Wiremock do?

Wiremock has a number of other interesting features that are worth looking at.
  • Standalone Deployment - Wiremock can be deployed as a standalone web app rather than being started and stopped with each integration test.
  • Mapping files can be used to configure stubs as an alternative to using just the API. This is useful is you have lots of stubs and you want to decouple their configuration from your tests. Mappings can be placed in a directory on your deployed Wiremock instance or registered by posting them to a Wiremock endpoint.
  • Proxying - Wiremock can be used to proxy calls to a live API. Say for example you want to run the majority of your integration tests against a live API, but you'd like to use Wiremock stubs for testing fault tolerance scenarios. Wiremock can be used as a proxy so that it forwards some requests to the live API and responds with stubs for other. This is a powerful feature as it allows you to mix stubbed and real responses in the same suit of tests.   

Wrapping Up 

This post looked at how Wiremock can be used to stub remote endpoints and provide a simple way to test a variety of integration scenarios. From what I've seen Wiremock isn't an alternative to live end to end integration testing, but rather something that can compliment it.  As always, if you have any questions or suggestions, please leave a comment below.

Comments

  1. Pablo Hidalgo31 October 2016 at 13:12

    Hi Brian! Great example... but i'm having trouble with the 'assertThat' methods in CostumerResourceTest.java... I'm getting 'The method assertThat(T, Matcher) in the type Assert is not applicable for the arguments ({diferent type of arguments})'... my 'assertThat' import is 'org.junit.Assert.assertThat'... any ideas? Thank you very much!

    ReplyDelete
  2. Brian31 October 2016 at 13:47

    Hi Pablo. Have a look at the source for CustomerResourceTest.java at https://github.com/briansjavablog/wiremock-demo/blob/master/src/test/java/com/blog/samples/test/CustomerResourceTest.java. You'll see that the assertThat is used in conjunction with some Hamcrest imports.

    ReplyDelete
  3. Selva Ganesh31 March 2017 at 05:35

    I am new to wiremock and as per client requirement , I have to use wiremock in our project but the thing is I have to write wiremock related code in .NET not in Java but I did not find any reference for Wiremock with .NET. Could you please help me with sample code to use wiremock in .NET. requirement : we have a API service , we have to mock that service using wiremock and write Xunit test case in C#.NET

    ReplyDelete

Post a Comment

Popular posts from this blog

Spring Web Services Tutorial

Image
Update
I've recently written a more up to date version of this post which describes how to build a contract first web service using Apache CXF. Check it out here.

Introduction
Modern enterprise applications are rarely stand alone and often rely on data and services provided by external systems. In order for different types of systems to communicate there must be a  communication protocol of some sort, a standard way of sending and receiving messages in a format that is recognised and supported by all major platforms. SOAP (Simple Object Application Protocol) is such a protocol, and allows applications to communicate by exchanging messages in a standard XML format.
SOAP Web Services provide a platform agnostic integration mechanism that allows disparate systems to exchange data regardless of the platform they are running on. For example, SOAP web services are commonly used to integrate .NET applications with applications running on the Java platform. Almost all modern platforms and …
Read more

REST Endpoint Testing With MockMvc

In this post I'm going to show you how to test a Spring MVC Rest endpoint without deploying your application to a server. In the past, full integration tests were the only meaningful way to test a Spring REST endpoint. This involved spinning up a test server like Tomcat or Jetty, deploying the application, calling the test endpoint, running some assertions and then terminating the server. While this is an effective way to test an endpoint, it isn't particularly fast. We're forced to wait while the entire application is stood up, just to test a single endpoint.
An alternative approach is to unit test by manually instantiating the Controller and mocking out any required dependencies.  While such a test will run much faster than a full integration test, its of limited value. The problem is that by manually instantiating the Controller we're bypassing Springs Dispatcher Servlet, and as a result missing out on core features like
request URL mapping request deserialization re…
Read more

Spring Batch Tutorial

Image
Introduction Spring batch is a lightweight framework that provides a solid foundation on which to build robust and scalable batch applications. It provides developers with a set of tried and tested patterns that solve common batch problems and allows developers to focus more on the business requirement and less on complex batch infrastructure. Spring batch contains a variety of out of the box configurable components that can be used to satisfy many of the most common batch use cases. Extensive XML configuration and an extensible programming model mean that these components can be customised and used as building blocks to quickly deliver common batch functionality.
This tutorial will show you how to build a very simple batch application to read fixed length data from a flat file and write it to a database table. This is a common batch use case and should be sufficient to demonstrate some of the fundamental concepts of Spring batch and provide you with a foundation on which to build mor…
Read more

Externalising Spring Configuration

Enterprise applications typically contain a number of  properties and  runtime resources that must be configured before the application is deployed. Property and resource values can either be baked into the artefact at build time using something like Maven Profiles or derived at runtime using Spring Profiles. My preferred approach is to externalise all configuration so that the artefact taken from the build server is environment agnostic and can be deployed onto any environment . For example, we could take a WAR file from our build server and  deploy it to our development, UAT or production environments without changing any configuration in the WAR file itself.

Spring Property Configuration Spring applications use the PropertyPlaceholderConfigurer to load application properties. Property files are typically loaded from the class path but the example below uses a slightly different approach, loading the properties file from a directory outside of the application itself. This allows the…
Read more

Axis2 Web Service Client Tutorial

Image
Introduction
Axis2 is a Java framework that provides comprehensive support for exposing and consuming web services. This short post will look at its SOAP client support and how it can be used to get a simple web service client up and running.
For convenience I'm going to be calling a web service that I recently built as part of another blog post.  If you don't already have a web service to call you can grab the full source code for my sample service from github. Simply run a Maven build and deploy the WAR to your Servlet container.

What is a Web Service Client
This post doesn't attempt to explain the detailed inner workings of a web service client, but its still pretty useful to have an idea of what's going on under the hood. Most web service clients provide the following
A client side proxy for the remote service we want to call, that allows our application to invoke a SOAP service using a simple method call. The proxy insulates our application from the intricacies of s…
Read more

Docker & Spring Boot

Docker allows you to package an application with its dependencies, into a light weight, portable container that can run on almost any environment.  You can think of a Docker container as a run time, a mini virtual machine that encapsulates your application and its dependencies.
In order to run a container you need a Docker image. An image is like a template that defines everything that will exist within the container. You can almost think of an container as a run time instance of the image it was created from. In this post we'll define and build 3 slightly different Docker images that run a simple Java app.

Installing Docker If you haven't already done so you'll need to install Docker. The official documentation is pretty good so following it step by step should see you up and running in about 15 minutes.
I've installed Docker on Windows and Ubuntu but to be honest I prefer running it on Ubuntu and have found it a bit more reliable than with Docker Toolbox on Windows.��…
Read more

jQuery Tables

Introduction
This post will show you how to create rich data grids using the DataTables plugin for jQuery. DataTables is a flexible framework that allows you to create grids using a variety of data sources. This tutorial will show you how DataTables can be used with DOM and JavaScript data sources.

DOM Data Source
The simplest way to use DataTables is with a DOM data source. This approach simply 'decorates' an existing HTML table and is ideal for enhancing plain HTML tables created using template languages like JSP or Velocity.

MakeModelBody ShapeEngine Size (Cubic Capacity)Horse PowerBMW320dSaloon2000181BMW330dCoupe3000231BMW335dEstate3000286BMW335iSaloon3000306BMWM3Coupe4000415BMW520dSaloon2000181BMW530dSaloon3000231BMW535dEstate3000286BMW535iSaloon4000306BMWM5Saloon5000508
To turn this rather dull looking HTML table into a rich data grid we simply decorate the table on document load.
1: <script type="text/javascript"> 2: $(document).ready(func…
Read more

Health Checks, Metrics & More with Spring Boot Actuator

Image
I've been working with Spring Boot for a few years now and I'm a big fan. There are lots of things to like about Spring Boot, but one thing that really stands out for me is the emphasis on production readiness.
Production Readiness Production readiness is about looking beyond functional requirements and ensuring your application can be properly managed and monitored in production. Some key things to consider when thinking about production readiness are...
Health checksViewing application configuration - application properties, Environment variables etc. Viewing and altering log configurationViewing application metrics - JVM, classloader, threading and garbage collection. Audibility of key application events Spring provides all of this functionality out of the box via Spring Boot Actuator, a sub project of Spring Boot. A range of RESTful management and monitoring endpoints are provided so you don't have to implement these features each time you build an application. To enable…
Read more