Mule 4 WireMock Module
Mule 4 WireMock Module
In this article, we discuss the value of HTTP test doubles in the context of integration tests and introduce the WireMock module to use in Mule 4
Join the DZone community and get the full member experience.Join For Free
In this post, we'll talk about the value of HTTP test doubles in the context of integration tests and introduce the WireMock module to use in Mule 4.
Integration Tests and WireMock
When writing integration software for distributed systems the most critical part to test is the interaction between those systems. Obviously, this makes integration tests vital. Traditionally, we would test against live systems, but having a local instance of an upstream system or a dedicated test instance can be expensive and/or difficult to coordinate its state between tests.
Instead, we can opt to verify the interactions against test doubles, also known as narrow integration tests. WireMock is a pretty popular HTTP server test double that allows us to configure stubbed responses for particular requests, as well as verifying that the requests it received match what we expect the system under test to have made.
Here are some more in-depth resources worth checking out on integration tests:
You may also like: Mocking REST API With WireMock — Recording and Manual Modes
Mule 4 Module
For one reason or another, WireMock had not made its way into Mule's homegrown test framework, MUnit. There's been support for Database test doubles with H2 in-memory database, but not for HTTP. So we've addressed that in the Mule 4 WireMock Module.
With the Mule WireMock Module, we can spin up an in-process HTTP Server and run our integration tests against it. WireMock gives us a couple of advantages over MUnit's 'Mock When' processor:
- We're actually sending requests over the wire so we get the confidence that HTTP Requester configuration and subsequent processors are correct.
- WireMock supports conditional responses based on scenarios. This way, we can more easily test behavior that changes the external system's state as it executes.
- With an actual HTTP Server serving requests, we can follow a TDD approach if the real services are not yet available or it's difficult to control their state.
Using the Connector
Add this dependency to your mule application's pom.xml:
Now, the palette and Global Elements should have the WireMock components:
The first thing we want to do is configure the WireMock Server. For that, we use the Global Configuration Element WireMock Config. Here's the simplest config example:
This tells Mule to start a regular HTTP WireMock server listening on all interfaces at port 8080, this is all the same as the stock HTTP server. The first added attribute is
resources, this is the directory WireMock will use for its
To understand how to use the module we must understand what purpose these directories serve to WireMock.
The Mappings Directory
WireMock is primarily meant to be configured with Java code, but it also has the ability to read request/response stub configurations serialized as JSON files.
mappings is the directory within
resources where WireMock will look for and parse *.json files as stubs.
Here's a simple example of stub.json mapping file:
This stub tells WireMock that when a POST request comes int at
/service-2 to reply with a 204 No Content.
The __files Directory
At some point, we may want to actually include response bodies in a stub. There's many ways to do that depending on the media type of the response. One of the easiest ways is to use
bodyFilename in the stub:
This stub tells WireMock to look for
service-3-ok-response.xml within the
__files directory and use it as the response's body.
Pointing to WireMock
It's important to understand that WireMock is a live HTTP server, meaning we want to:
- Not use 'Mock When' to bypass HTTP Requesters in your flows.
- Point those HTTP Requesters to the WireMock HTTP server.
Normally, things like an external HTTP dependency host and port will be properties put away in a environment-specific file. However, they are provided into the application, so we want to make sure that when running in MUnit, they point to the WireMock server.
In our example, that is localhost:8080, so that's what the HTTP Requesters need to use when going through the implementing flow.
As a side note, it might be a good idea to use "MUnit Dynamic Port." This allows a CI pipeline to run tests from different artifacts and avoid port conflicts.
The Integration Test
Let's assume that our application exposed a service at
/system-under-test/service-1, so our MUnit integration test might look something like this:
In this test, we're making a live call to
/system-under-test as well as not using 'Mock When' to bypass any HTTP Requesters in the implementing flow.
To assert our service's output, we're using MUnit Tools to assert the status code and body match what we expect. As long as the appropriate stubs are set up in
mappings, the test should pass.
Verifiying Outgoing Requests
In order to increase the level of confidence we have on the integration of this service with external services, we can verify with WireMock that the requests it received match what we expected them to be: That X header's value was as it should, that one particular field in the response body was as it should, etc.
Let's assume that
/system-under-test needed to GET something from an external
/service-1 and subsequently POST to an external
For that, we can add something like this after we've asserted the system under test's output:
Take a look at the module's own integration test for the working MUnit.
In general the Mule 4 module only exposes WireMock's functionality as-is while relying heavily on its JSON representation of stubs and verification objects.
For more details on stubbing responses and verifying requests, see:
And look for "in JSON" or "via JSON API" to see how you can do things using the module.
Integration services User Acceptance Tests
With tests like these, we test the integration with our service from the perspective of our consumers and the integration of the system under test with external HTTP services; effectively serving as a user acceptance test for Mule 4 integration services.
Opinions expressed by DZone contributors are their own.