# MockServer — Mock Any Server or Service via HTTP and HTTPS

> MockServer is a Java-based tool for mocking and proxying HTTP and HTTPS services. It lets developers define request-response expectations programmatically or via JSON, acting as a stub server for integration testing, a proxy recorder for capturing real traffic, and a verification tool for asserting expected API interactions.

## Install

Save as a script file and run:

# MockServer — Mock Any Server or Service via HTTP and HTTPS

## Quick Use
```bash
# Run with Docker
docker run -d -p 1080:1080 mockserver/mockserver
# Set up an expectation via REST API
curl -X PUT http://localhost:1080/mockserver/expectation -d '{"httpRequest":{"path":"/api/users"},"httpResponse":{"body":"{"id":1}","statusCode":200}}'
# Test the mock
curl http://localhost:1080/api/users
```

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

---
Source: https://tokrepo.com/en/workflows/asset-1421f19b
Author: Script Depot