MockServer — Mock Any Server or Service via HTTP and HTTPS

Introduction

MockServer enables developers to mock any HTTP or HTTPS service for integration testing, development, and debugging. It supports defining expectations through a REST API, Java client, or JSON configuration, and can also act as a recording proxy that captures real traffic for later replay.

What MockServer Does

• Stubs HTTP and HTTPS endpoints with configurable request matchers and response templates
• Records and replays traffic when running as a proxy in front of real services
• Verifies that expected requests were made with correct headers, body, and parameters
• Supports dynamic responses with JavaScript templates, delays, and connection drops
• Runs as a Docker container, JUnit rule, Maven plugin, or standalone JAR

Architecture Overview

MockServer is a Netty-based Java application that listens on configured ports for HTTP and HTTPS connections. Incoming requests are matched against a list of expectations ordered by priority. Each expectation defines request matchers (path, headers, body, query params) and an action (respond, forward, callback, or error). When acting as a proxy, it forwards requests to the real service and records the exchange. The REST API and web UI allow runtime management of expectations and verification of logged requests.

Self-Hosting & Configuration

• Run via Docker: docker run -d -p 1080:1080 mockserver/mockserver
• Add as a Maven or Gradle dependency for JUnit-based test suites
• Configure TLS with custom certificates for HTTPS mocking
• Define expectations in JSON files loaded at startup for repeatable test environments
• Use environment variables to set log levels, max expectations, and memory limits

Key Features

• Rich request matching by path, regex, JSON body, JSON schema, XPath, and headers
• Dynamic response templating with JavaScript, Velocity, or Mustache templates
• Proxy mode records real API traffic and generates expectations automatically
• Request verification API asserts that specific calls were made during a test
• Web dashboard visualizes active expectations, logged requests, and matched responses

Comparison with Similar Tools

• WireMock — Similar Java-based mocking; MockServer adds proxy recording and JavaScript templates
• MSW (Mock Service Worker) — Browser and Node.js interception; MockServer is a standalone server for backend integration tests
• Hoverfly — Go-based simulation proxy; MockServer has richer Java ecosystem integration
• Prism — OpenAPI-based mock server; MockServer is schema-agnostic with manual expectation control
• JSON Server — Simple REST fake server; MockServer provides full request matching and verification

FAQ

Q: Can MockServer mock WebSocket connections? A: MockServer focuses on HTTP and HTTPS. For WebSocket mocking, consider using a dedicated WebSocket mock tool alongside it.

Q: How do I use MockServer in JUnit tests? A: Add the mockserver-junit-jupiter dependency and use the @ExtendWith(MockServerExtension.class) annotation to automatically start and stop the server per test class.

Q: Can I simulate slow responses or errors? A: Yes. Expectations support response delays, connection drops, and custom error codes to test timeout handling and error recovery in clients.

Q: Does MockServer support HTTPS with custom certificates? A: Yes. You can provide your own CA certificate and private key so MockServer generates dynamic certificates for any hostname, enabling transparent HTTPS mocking.

Sources

• https://github.com/mock-server/mockserver
• https://www.mock-server.com/