Facilitating the Spread of Knowledge and Innovation in Professional Software Development

Write for InfoQ


Choose your language

InfoQ Homepage News API Mocking Tool WireMock v2 Released with Improved Request Matching and Stub Management

API Mocking Tool WireMock v2 Released with Improved Request Matching and Stub Management

This item in japanese


WireMock v2, an API mocking and service virtualisation tool, has been released. Core enhancements include improved request verification failure reporting, the ability to create custom request matching logic (including the use of Java 8 lambdas), support for gzipped request and response bodies, randomly distributed delays (currently with uniform and lognormal distributions), and matching on cookies and basic auth headers.

InfoQ recently sat down with WireMock creator Tom Akehurst and asked questions about the new features of WireMock v2, the role service virtualisation plays within modern architectures, and the relationship between mocking and contract validation.

InfoQ: Hi Tom, and welcome to InfoQ! Could you briefly introduce yourself please, and tell us about WireMock?

Akehurst: Hello! I'm Tom Akehurst. By day I help clients build better tech with Energized Work in London, by night (and weekends) I maintain WireMock.

I'd describe WireMock as an API mocking or Service Virtualisation tool. In essence it allows you to stub or mock HTTP interactions with systems your app depends on for testing. Some benefits of this include:

  • Staying productive when the API you depend on isn't complete or doesn't exist.
  • Reduced dependency on test environments and 3rd party sandboxes.
  • Much faster test runs (can be 10x or more) vs. testing against real systems.
  • Easily testing edge cases and failure modes, including nasty stuff like dropped TCP connections and latency spikes.

You can find documentation and other info at

InfoQ: Can you talk about the new features introduced in the recent v2 release of WireMock?

Akehurst: WireMock v2 introduced the concept of "distance" between a stub definition and a request. This enabled some big improvements in reporting unmatched requests and verification failures. When a verify call fails to match a request, WireMock now finds the most similar one and presents a diff. This vastly reduces the effort in, for example, finding that one character you forgot to capitalise when you've just tested a feature involving a half a dozen HTTP POSTs.

The extensions API is now richer. Response transformers can now take parameters and transform proxied responses. Custom request matching logic can also now be used, including via Java 8 lambdas.

Although it was possible to run WireMock 1.x on Android, this involved maintaining a private fork with some source hacks to work around library incompatibilities. Thanks to some help from a few folks in the Android community, this now only involves a handful of lines added to your build file.

Other changes of note include:

  • Support for gzipped request and response bodies.
  • Randomly distributed delays - currently with uniform and lognormal distributions.
  • Matching on cookies and basic auth headers.
  • Editing, deleting and (re)saving of stub mappings.
  • Upgrade to Jetty 9, with improved performance, fewer Servlet API dependency headaches and bug fixes.
  • The standard and standalone JARs are now separate Maven artifacts, meaning you don't have to exclude swathes of transitive dependencies if you want to depend on the standalone JAR.

InfoQ: How many developers do you believe are aware of the service virtualisation technique (in comparison with say, mocking or stubbing), and can you share some particular use cases that a tool like WireMock excels?

Akehurst: A quick check of Google Trends shows Mockito getting about 10x the search volume of WireMock, so (somewhat unscientifically!) I think it's fair to say there's a way to go before SV mindshare catches up with object mocking.

But interest in tools like WireMock seems to have trended upwards sharply in the last year or two. One possible explanation for this is the explosion in popularity of microservices. I'm increasingly finding that WireMock users I speak to are using it in microservice testing setups, and I'd say this is definitely a sweet spot.

Other use cases where WireMock can add a lot of value:

  • Component testing - running acceptance tests against a single service/app at near unit test speed. Although object mocks can be substituted at a system boundary for this, using WireMock means that HTTP clients, resource pools, and serialisation/deserialisation are all covered.
  • Fault scenarios e.g. socket disconnection. These can be very difficult to model correctly with object mocking tools, and similarly difficult to simulate in real systems.
  • Isolated performance testing - measuring the performance of a single component. Again, object mocks can be substituted at a system boundary for this, but the results are likely to be skewed as they ignore the impact of HTTP clients, connection pooling, threading etc.

InfoQ: Can you share any 'best practices' for creating tests using a service virtualisation tool like WireMock? Are there any particular methodologies that complement WireMock-driven testing, like BDD?

Akehurst: A few things I've learnt talking to WireMock users and from client work:

  • Use record/playback sparingly. Like with UI automation tools, recording something that's changing regularly quickly generates a lot of maintenance effort.
  • Much as you'd write page objects for your UI tests, write builders and service wrappers around your stubbing and verification code. This is a bit laborious initially, but in the long run it pays dividends in ease of maintenance and readability.
  • Write fault injection tests - drop connections, return 5xx responses, add delays to trigger socket timeouts. Not only will this catch the kind of problems that burn you in production at 3am, but you can also check that your healthchecks and monitoring work correctly. If you're running on the JVM (or Android) you can get feedback on a whole range of resilience risks at unit test speed, which definitely beats waiting for your chaos monkey to tell you!

WireMock plays very nicely with BDD tools. A very common pattern I've both seen and used is to configure stubs in the "Given" portion of a scenario, then verify interactions in the "Then" part.

InfoQ: How do you think service virtualisation might relate to contract first development. Is there some overlap?

Akehurst: I can't claim much authority on this as I've only recently been dipping my toe in the water. However, machine-readable specs (e.g. Swagger or RAML) look like a very promising way to solve the issue of detecting when stub definitions drift from reality.

Another interesting approach is taken by Spring Contract Verifier, which generates WireMock stub definitions from its contract specs so that clients can be tested in isolation.

InfoQ: Do you think a tool like WireMock would be useful for testing non-functional requirements?

Akehurst: Absolutely! Performance, resilience and security are all characteristics I've tested and seen tested using WireMock.

To give an example, the random delays feature mentioned above was the result of a pull request from a team using WireMock to do continuous performance testing of their microservices. Their delivery pipeline ensured each of their services passed a performance benchmark in isolation before allowing promotion into shared environments.

From a resilience point of view, I once wrote a soak test with some fault injection which demonstrated that an application gradually leaked pooled connections when a 3rd party system returned proxy errors.

InfoQ: The WireMock website mentions that you are creating a SaaS-based offering named MockLab. Would you like to share any more details with the InfoQ audience?

Akehurst: Lately, I've been encountering increasingly elaborate WireMock setups in the wild. I've seen teams invest serious engineering effort in deploying/managing swarms of WireMock instances, and building bespoke UIs over the top to aid exploratory testing and demoing.

MockLab aims to massively reduce the effort of managing farms of WireMock instances, enabling deployment of mock services in a few clicks. It will also make test setup and analysis accessible to folks who don't live and breathe in code.

If you're building (or testing!) mobile apps, microservices or a system that depends on 3rd party APIs, I'd definitely recommend taking a look.

For more info and if you'd like to be notified when MockLab becomes available, please visit the pre-launch page:

InfoQ: Thanks for talking to InfoQ today Tom. Is there anything else you would like to share with our readers?

Akehurst: Just to say a big thanks to all the folks who helped me get v2 over the line. Full credits are given at, but I'd like to single out Sam Edwards, Rob Elliot and Rowan Hill in particular for their time and patience. Cheers chaps!

More information on WireMock v2 can be found on the project website, and the code be found in Tom Akehurst’s GitHub account.

Rate this Article