mock-server/mockserver-monorepo

MockServer – Quick Overview

What it is – MockServer is a single‑binary tool that lets you mock, record, and chaos‑test any HTTP‑based dependency (HTTP/1, HTTP/2, HTTPS, gRPC, WebSockets, raw TCP, even experimental HTTP/3). It can also act as a proxy that records real traffic, injects latency or errors, and rewrites requests on the fly.

Why it matters for AI/ML projects – Modern AI services (OpenAI, Anthropic, Gemini, Bedrock, Azure OpenAI, Ollama, etc.) are accessed over HTTP APIs. MockServer lets you spin up a local stand‑in for those endpoints, generate responses from OpenAPI specs, or even simulate the chat‑completion APIs with templated or callback‑driven replies. This makes integration tests fast, deterministic, and safe – no need to hit a real paid model during CI.

Key features

• Protocol‑agnostic port – One listening port automatically detects HTTP, HTTPS, HTTP/2, gRPC, gRPC‑Web, WebSockets, raw TCP, and experimental HTTP/3.
• Mock, proxy, or both – Define static expectations, use templating/callbacks, or run as a forward proxy that records and mutates live traffic.
• Chaos engineering – Inject latency, drop connections, or force error responses to test resilience.
• AI‑specific mocks – Built‑in support for major LLM chat‑completion APIs, including streaming responses.
• Spec‑driven generation – Import an OpenAPI/Swagger file and automatically create request‑matching expectations.
• Multi‑language client libraries – Java, Node, Python, Ruby, Go, .NET, Rust, PHP, plus JUnit & Spring test helpers.
• Deployment flexibility – Docker, Helm/Kubernetes, plain JAR/WAR, JVM‑less binary, Homebrew CLI, Testcontainers, or as a Maven/Gradle dependency.
• Dashboard & MCP integration – Web UI for live inspection and a Model‑Context‑Protocol (MCP) server so AI coding assistants can drive MockServer directly.

Getting started in 60 seconds

# Docker (most common)
docker run -d --rm -p 1080:1080 mockserver/mockserver
# Define a simple expectation
curl -X PUT http://localhost:1080/mockserver/expectation \
  -H 'Content-Type: application/json' \
  -d '{"httpRequest":{"method":"GET","path":"/hello"},"httpResponse":{"statusCode":200,"body":"Hello World"}}'
# Call the mock
curl http://localhost:1080/hello   # → Hello World

You can also install the mockserver CLI via Homebrew and run mockserver run --port 1080.

Typical use cases for AI/ML developers

1. Unit / integration testing of LLM‑calling code – replace the real OpenAI endpoint with a deterministic mock that returns a fixed JSON payload or streams chunks.
2. Contract testing – generate expectations from the provider’s OpenAPI spec and verify your client respects the contract.
3. Performance & resilience testing – use the chaos features to simulate latency spikes or dropped connections that often happen in cloud‑hosted AI services.
4. Local development – run the Docker image or binary on a laptop, avoiding network latency and API‑key leakage.
5. End‑to‑end CI pipelines – spin up a MockServer container in GitHub Actions, GitLab CI, or Jenkins, run your test suite, then discard the container.

Installation options

Channel	Command
Docker	docker run -d --rm -p 1080:1080 mockserver/mockserver
GHCR Docker	docker run -d --rm -p 1080:1080 ghcr.io/mock-server/mockserver
Homebrew (macOS/Linux)	brew install mockserver
Helm (K8s)	helm upgrade --install --namespace mockserver mockserver oci://ghcr.io/mock-server/charts/mockserver
Maven (Java)	org.mock-server:mockserver-netty-no-dependencies
npm (Node)	mockserver-node
PyPI (Python)	mockserver-client
RubyGems	mockserver-client
Cargo (Rust)	mockserver-client
NuGet (.NET)	MockServerClient

Community & support – Active GitHub issues, Discussions, a public roadmap, and a variety of client SDKs. The project also provides a React‑based admin UI (MockServer Browser Admin) for visual management of expectations.

---

Bottom line – MockServer is a mature, language‑agnostic testing tool that fits naturally into AI/ML workflows where external HTTP‑based services (especially LLM APIs) need to be stubbed, recorded, or stress‑tested.