WireMock: stubs, recording, and a 4.x line still in beta at build 41

Four ways to define a mock, and recording is the fastest to a first stub set

WireMock supports several approaches to creating mock APIs, and the choice is not stylistic. You can define stubs in code, push configuration through its own REST API, keep them as JSON files, or record the HTTP traffic of a proxied destination and replay it. The recording route is the one that changes a team's first afternoon: point it at a real service, exercise the paths, and you have a stub set that matches reality, including the headers real clients send. The JSON file route is the one you commit to a repository, which makes stubs reviewable in a pull request instead of buried in test code. The code route composes best with a fluent Java API. The consequence is that the artefact you hand to a colleague can be code, a file, or a fixture directory, and it is worth deciding early which of those your team treats as source.

Matching runs against any part of the request, and responses are templated

The matching system is the reason this tool outlives simpler stub maps. A stub can be matched on URL, on header and on body content patterns, and the project describes a rich matching system that allows any part of an incoming request to be matched against complex and precise criteria. So a test can assert that your client sends a particular content type and a particular field value, not merely that it called a path. Responses go the other way: they can be dynamically generated through a Handlebars-based templating system, which is what lets one stub answer differently depending on what was sent. The consequence for a team is that a fixture stops being a blob copied from a terminal and becomes a specification. The cost is that you now maintain matchers, and a matcher that is too precise will fail for reasons that look like application bugs until you read it.

Fault injection, delays and state are what separate it from a fixed response

Look at the features that are not about returning a body, because they are the reason to use a mocking server rather than a hand-written fake. There is fault and response delay injection, which lets you make an endpoint fail or hang on demand. There is per-request conditional proxying, so some calls go upstream while others are served locally. There is request verification, which turns a call you did not expect into a test failure rather than a passing no-op. There is stateful behaviour simulation, so a stub can advance across a sequence. And there is browser proxying for request inspection and replacement, which is how you capture the calls a browser actually makes. The consequence is that your own service can be tested against timeouts, retries and ordering, which is the part of an integration test suite that usually gets skipped because it is hard.

One repository, seven modules, and the artifact decides how you use it

The tree is a multi-module Gradle build and the module names are the API surface. There is a core module, a standalone module, a Jetty module, separate JUnit 4 and JUnit 5 integrations, a URL handling module and an HTTP client adapter. Around them sit the usual pieces of a large Java project: a build logic directory, performance tests, a sample web application, schema files, scripts, a test logging directory, a user interface directory, and toolchain files pinning both a JVM and Node. So the practical decision is which artifact you depend on. A unit test wants the integration module for your JUnit version, a container wants the standalone build, and an application embedding a server wants the Jetty one. Nothing forces one choice, and the toolchain files suggest the project expects contributors to hit a specific JVM and Node version before anything else.

4.x has been in beta across at least thirty-nine builds

The release list is entirely prereleases of one major version: a beta numbered 39 on 2026-09-24, 40 on 2026-10-07 and 41 on 2026-10-21, with the last push on the default branch dated 2026-11-02. The project is not archived, and it began in 2011 as a Java library, which is a long enough history to treat the beta counter as normal here rather than alarming. The practical consequence is that pinning is not optional for a team on the current line. A beta number is the unit of upgrade, and there is no stable 4.x to sit on, so the decision about when to move is a decision about a specific beta rather than about a major release. The companion hosted product is what the open source work supports, and the README suggests it for teams that need advanced capabilities.

The breaking-change report has a filtered mode for the published API only

Upgrading a mocking library used to break builds in confusing ways, and this project publishes a report instead. A binary compatibility report compares the current build against the last 3.x release and lists the binary-incompatible changes, filtered to classes annotated as published API. If you have a coding assistant installed, the README describes a single command that produces a filtered summary:

/breaking-change-report

And the raw route, which works without that tool, is a Gradle task:

./gradlew :wiremock-core:japicmp

The reports land in a directory under the core module, and the table distinguishes three files: the full HTML report covering all public classes, the same thing as plain text, and the filtered Markdown file restricted to the published API. The page warns that the unfiltered report also includes classes never intended to be part of the published API. So the third file is the one to read before you upgrade a large test suite.

The log4j note is a dependency answer, not a reassurance

One short section exists because security scanners keep producing findings. The statement is precise: the project uses that logging library only in its test dependencies, neither the thin nor the standalone archive depends on or embeds it, and you can continue using version 2.32.0 and above without exposure to the vulnerability that prompted the question. That is the kind of claim worth reading in full, because a scanner that walks your test classpath will still find it and you will have to decide whether to suppress the finding. The consequence is a small amount of work either way. If your organisation does not scan test dependencies you have nothing to do. If it does, this paragraph plus the artifact you actually ship is the answer to put in front of the person who raised the ticket.

Editorial conclusion

Adopt it when your tests break because a third party is slow, flaky or absent, and when you want your service's own tests to cover retries and timeouts. Do not adopt it as a substitute for contract testing against the real API, since the value is in being wrong in a controlled way. Before you move to 4.x, generate the breaking-change report for the version you are considering and read the filtered file, and check the log4j note if a dependency scanner has flagged your test classpath.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. wiremock/wiremock on GitHub