# WireMock — Flexible API Mocking for Java and Beyond

> WireMock is an HTTP mock server for stubbing and verifying API calls in integration tests and development.

## Install

Save in your project root:

# WireMock — Flexible API Mocking for Java and Beyond

## Quick Use
```bash
# Standalone server
docker run -it --rm -p 8080:8080 wiremock/wiremock:latest

# Stub an endpoint
curl -X POST http://localhost:8080/__admin/mappings -d '{"request":{"method":"GET","url":"/api/users"},"response":{"status":200,"jsonBody":{"users":[]}}}'

# Test it
curl http://localhost:8080/api/users
```

## 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/

---
Source: https://tokrepo.com/en/workflows/3a70e5d9-4278-11f1-9bc6-00163e2b0d79
Author: AI Open Source