WireMock — Flexible API Mocking for Java and Beyond

Introduction

WireMock is a simulator for HTTP-based APIs that lets developers create realistic stubs, record and replay traffic, and verify that downstream services were called correctly. It runs as a standalone server, a Docker container, or embedded within JVM test suites. WireMock eliminates the need for live external services during integration testing.

What WireMock Does

• Stubs HTTP endpoints with configurable responses including status, headers, body, and delays
• Records live API traffic and replays it as deterministic stubs
• Verifies that requests were made with expected parameters, headers, and bodies
• Simulates faults like timeouts, connection resets, and slow responses
• Matches requests using URL patterns, JSON path, XPath, and regex

Architecture Overview

WireMock runs a Jetty-based HTTP server that intercepts incoming requests and matches them against a list of stub mappings. Mappings are stored in memory or on disk as JSON files. The matching engine evaluates URL patterns, headers, query parameters, and body content in priority order. When recording, a proxy forwards requests to the real API and saves the response as a new mapping. The admin API at /__admin allows runtime configuration without restarts.

Self-Hosting & Configuration

• Run standalone via Docker, the JAR file, or as an embedded JUnit rule/extension
• Store stub mappings as JSON in a mappings/ directory for version control
• Use --global-response-templating for dynamic responses with Handlebars expressions
• Set --proxy-via to forward unmatched requests to a real backend
• Configure HTTPS with --https-port and custom keystores for TLS testing

Key Features

• Request matching supports URL, header, query, cookie, and body-level patterns
• Response templating with Handlebars allows dynamic values like timestamps and random data
• Fault injection simulates network delays, dropped connections, and malformed responses
• Record-and-playback captures real API interactions for offline test replay
• Multi-language clients available for Java, Python, Go, .NET, and Ruby

Comparison with Similar Tools

• Mockito — mocks Java objects in-process; WireMock mocks at the HTTP layer
• MockServer — similar HTTP mocking; WireMock has a larger ecosystem and richer templating
• Hoverfly — proxy-based with simulation modes; WireMock offers more flexible request matching
• Prism — generates mocks from OpenAPI specs; WireMock supports arbitrary stub definitions
• json-server — quick REST mock from a JSON file; WireMock adds fault simulation and verification

FAQ

Q: Can I use WireMock outside of Java projects? A: Yes. Run the standalone JAR or Docker image and configure stubs via the HTTP admin API from any language.

Q: How do I match requests by JSON body content? A: Use bodyPatterns with equalToJson, matchesJsonPath, or matchesJsonSchema matchers.

Q: Does WireMock support gRPC? A: WireMock has a gRPC extension that can stub and verify Protocol Buffer-based services.

Q: Can I run multiple WireMock instances in parallel? A: Yes. Use different ports or the JUnit 5 extension which assigns dynamic ports per test class.

Sources

• https://github.com/wiremock/wiremock
• https://wiremock.org/docs/