# WireMock: a mock HTTP server you can run in a JUnit test, a container or on its own

> WireMock stubs HTTP services so tests and development environments stop depending on flaky third parties. It runs as a Java library, a standalone process or a container, and the current line is still in beta.

**wiremock/wiremock** — A tool for mocking HTTP services

- Repository: https://github.com/wiremock/wiremock
- Website: https://wiremock.org/
- Stars: 7,384 · Forks: 1,519
- Language: Java
- License: Apache-2.0
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/wiremock-wiremock

## The problem WireMock removes: an HTTP dependency you do not control

A test that calls a real third party API is a test that fails when that API is down, slow, rate limited or changed without notice. WireMock exists to stand in for that dependency. The README names three situations directly: creating stable test and development environments, isolating from flaky third parties, and simulating APIs that do not exist yet. The third case is the one teams often overlook. If a backend service has been specified but not built, a WireMock instance can serve the agreed response shape so the client team keeps working.

It is aimed at people who write tests against HTTP. That includes Java developers running unit and integration tests, but the README is explicit that the project spans multiple languages and stacks: it can run as a library or a client wrapper in many languages, or as a standalone server. A Python or .NET team that does not want a JVM in the test process can still use the standalone form and talk to it over HTTP. The project started in 2011 as a Java library and now ships several artifacts, including wiremock-junit4, wiremock-junit5, wiremock-standalone and a Jetty integration module.

## Stubs, matching and templating: how a request becomes a response

WireMock is an HTTP server that holds a set of stubs. Each stub pairs request matching criteria with a response. The README describes the matching system as rich, allowing any part of an incoming request to be matched against complex and precise criteria, and lists URL, header and body content patterns as the matchable surface. When a request arrives, WireMock evaluates it against the loaded stubs and returns the response from the first match.

There are four ways to create those stubs, and this is the part that decides how you integrate the tool. You can define them in code through a fluent Java API, post them as JSON over HTTP to the admin interface, load them as JSON files, or record them by proxying traffic to a real destination and capturing what comes back. The record and playback path is the fastest way to bootstrap a suite when a real service exists but is unreliable.

Responses are not limited to fixed bodies. The README states that responses of any complexity can be generated dynamically through a Handlebars based templating system, so a response body can be computed from the request. Stateful behaviour simulation is listed as a feature, which means a stub can change its answer across a sequence of calls rather than returning the same thing every time. Fault and response delays can be injected, and proxying can be conditional per request. The extension points are the escape hatch when matching or templating is not enough.

## Installing WireMock and running the breaking-change report

The README points to wiremock.org/docs for full documentation and does not print install commands itself. What it does show is the artifact naming: Maven Central hosts org.wiremock/wiremock, and the repository contains wiremock-standalone, wiremock-junit4, wiremock-junit5, wiremock-jetty, wiremock-httpclient-apache5 and wiremock-url as separate modules. Pick the artifact that matches how you intend to run it. The README does not document the standalone server's command line or its default port, so check the standalone documentation before you point anything at it.

The one command the README does reproduce is the japicmp breaking-change report. Running it compares the current build against the last 3.x release and lists binary-incompatible changes to classes annotated @PublishedAPI.

```bash
./gradlew :wiremock-core:japicmp
```

Reports are written to wiremock-core/build/reports/japicmp/. The README names three files there: breaking-changes.html for the full report across all public classes, breaking-changes.txt with the same content in plain text, and breaking-changes-published-api.md, which is filtered to @PublishedAPI classes only and is produced by the Claude Code skill. The README warns that the raw report includes classes not intended to be part of the published DSL, so the filtered file is the one to read when you are judging upgrade risk.

If you have Claude Code installed, the README gives a second route that runs the report and produces the filtered summary in one step.

```
/breaking-change-report
```

Beyond that, the README defers to the docs site and the contributing guide. It does not give a Maven or Gradle dependency snippet, a Docker run command, or a JUnit annotation example, so treat those as documentation lookups rather than something you can copy from the repository front page.

## Where WireMock stops being the right tool

WireMock is not a service virtualisation platform for arbitrary protocols. It speaks HTTP, and the feature list is entirely HTTP-shaped: URL, header and body matching, browser proxying, fault injection. If your dependency is a message broker, a database wire protocol or gRPC, this is not the tool for that job, and the README does not claim otherwise.

The second boundary is contract drift. A stub encodes what you believe the other service returns. Nothing in WireMock verifies that belief against the real service unless you record from it, and a recorded stub is a snapshot that goes stale the moment the provider changes. Teams that treat a green WireMock suite as proof of integration correctness are measuring their own assumptions.

The third issue is version maturity. The most recent releases listed are 4.0.0-beta.38, 4.0.0-beta.37 and 4.0.0-beta.36, published between 2026-06-05 and 2026-07-02. These are beta versions, and the README's own breaking-change tooling exists because the 4.x line changes binary-incompatible API surface. If your project cannot absorb that churn, pin to a 3.x release and read the japicmp report before upgrading.

## WireMock against a plain stubbing library or a hand-written fake server

The common alternative in a Java codebase is a mocking library such as Mockito applied to an HTTP client interface, or a hand-rolled fake server built on the JDK's com.sun.net.httpserver. The difference in approach is where the boundary sits. Mockito replaces a Java interface, so the test never exercises serialisation, status codes, headers or connection handling. WireMock replaces the HTTP endpoint, so the code under test makes a real network call and parses a real response.

That distinction decides which failures you catch. A Mockito stub will not tell you that your JSON deserialisation breaks on a 204 with no body, or that you forgot to set a Content-Type header. WireMock will, because the response travels over a socket. The cost is speed and setup: an HTTP server in the test process is heavier than a mock object, and stub definitions are more verbose than a when/then pair.

For Python teams the equivalent choice is responses or requests-mock, which patch the HTTP layer inside the process rather than starting a server. WireMock's advantage there is language neutrality: the standalone server does not care what language the client is written in, which is why the README can claim it spans multiple programming languages and technology stacks. If your tests are all in one language and never leave the process, an in-process library is simpler.

## Maintenance status, upgrade cost and the Apache-2.0 licence

The repository is not archived, and the last push was on 2026-09-18, four days before this article's reference point. That is active work on the master branch. The release cadence visible in the recent releases is roughly two to three weeks between 4.0.0 betas, which is a fast moving line.

Upgrade cost is the thing to budget for. The presence of a japicmp-based breaking-change report, and the fact that it compares against the last 3.x release, tells you the maintainers expect binary-incompatible changes and have built tooling to surface them. If you use the Java DSL, run ./gradlew :wiremock-core:japicmp or the /breaking-change-report skill before moving a production suite across a major version, and read the filtered breaking-changes-published-api.md rather than the full report.

The licence is Apache-2.0, with LICENSE.txt and NOTICE.txt at the repository root. Apache-2.0 permits commercial use and modification and includes a patent grant, but it also requires that you preserve the NOTICE file contents when redistributing. If you ship WireMock inside a product, check NOTICE.txt rather than assuming the licence header alone covers you. This is a description of the licence terms, not legal advice; your counsel decides what your distribution requires.

The README also carries a log4j notice: WireMock uses log4j only in its test dependencies, and neither the thin nor the standalone JAR depends on or embeds log4j, so the README states that versions 2.32.0 and above carry no exposure to that vulnerability. That claim is scoped to the JARs named, not to your application's own dependency tree.

## Conclusion

Adopt WireMock when your tests or a development environment need an HTTP dependency that is unavailable, slow or not written yet, and when stubbing on URL, header and body patterns is enough. Do not adopt it as a general network proxy or as a contract-testing framework for a service you already own. Before committing, check the 4.0.0 beta release notes for changes to the Java API you plan to use, and confirm which artifact matches your runtime: the library for JUnit, wiremock-standalone for a process, or the container image for Docker.

## FAQ

### What is WireMock used for?

It mocks HTTP services so tests and development environments stay stable, do not depend on flaky third parties, and can simulate APIs that do not exist yet. It runs in unit tests, as a standalone process or in a container.

### Is WireMock free to use?

The repository is licensed under Apache-2.0, with LICENSE.txt and NOTICE.txt at the root. The README also mentions a commercial product, WireMock Cloud, for teams that need advanced capabilities such as OpenAPI, dynamic state and data sources.

### What tools are similar to WireMock?

The README does not name alternatives. In Java, a mocking library such as Mockito replaces the client interface rather than the HTTP endpoint, so it never exercises status codes, headers or serialisation the way a WireMock stub does.

### Can I use WireMock with Spring Boot?

The README does not mention Spring Boot. It lists wiremock-junit4 and wiremock-junit5 among the repository modules, and states that WireMock can run in unit tests, as a standalone process or as a container, so the integration path depends on which of those you choose.

### How do I install WireMock?

The README does not print install commands; it points to wiremock.org/docs and lists the published artifacts. The modules in the repository include wiremock-standalone, which runs as a JAR, and wiremock-junit4 and wiremock-junit5 for test use.

### How does WireMock work?

It runs an HTTP server holding stubs that pair request matching criteria with responses. Stubs can be defined in code, posted as JSON over HTTP, loaded from JSON files, or recorded by proxying traffic to a real destination.

## Sources

- [License: Apache-2.0](https://github.com/wiremock/wiremock/blob/master/LICENSE)
- [Project website](https://wiremock.org/)
- [README](https://github.com/wiremock/wiremock/blob/master/README.md)
- [Releases](https://github.com/wiremock/wiremock/releases)
- [wiremock/wiremock on GitHub](https://github.com/wiremock/wiremock)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/wiremock-wiremock