Contributing to MockServer
May 30, 2026 · View on GitHub
This project is governed by the Code of Conduct. By participating, you are expected to uphold it.
Issues
If you have any problems, please check the project issues and avoid opening issues that have already been fixed. When you open an issue please provide:
- MockServer version
- How you are running MockServer (Maven plugin, Docker, JAR, etc.)
- MockServer log output at INFO level (or higher)
- What the error is
- What you are trying to do
Repository Structure
This is a monorepo containing several projects:
| Directory | Language | Description |
|---|---|---|
mockserver/ | Java | Main MockServer (Netty HTTP server + Maven plugin sibling module) |
mockserver/mockserver-maven-plugin/ | Java | Maven plugin for starting/stopping MockServer (separate build, inherits version from parent) |
mockserver-ui/ | TypeScript | Dashboard React SPA |
mockserver-node/ | JavaScript | Node.js launcher |
mockserver-client-node/ | JavaScript | Node.js/browser API client |
mockserver-client-python/ | Python | Python API client |
mockserver-client-ruby/ | Ruby | Ruby API client |
mockserver-performance-test/ | JavaScript | k6 performance tests |
For a deeper picture of how these fit together — module dependencies, the Netty pipeline, request matching, event system, dashboard, TLS — start with the code overview and follow the topic links in docs/README.md. High-level architecture: docs/architecture.md.
Where to make changes
Most contributions touch one of these areas. Skim the linked docs before opening a PR — they save asking maintainers where a feature should live.
| Change type | Module(s) | Key reference |
|---|---|---|
| New request matcher / matching behaviour | mockserver/mockserver-core (model + matchers + serialisation) | docs/code/request-processing.md, docs/code/domain-model.md |
| New action type (response/forward/error variant) | mockserver/mockserver-core action + mockserver-netty handler wiring | docs/code/request-processing.md |
| Netty pipeline / protocol detection / SSE / WebSocket / JSON-RPC | mockserver/mockserver-netty (handlers + unification) | docs/code/netty-pipeline.md, docs/code/ai-protocol-mocking.md |
| TLS, mTLS, certificates, JWT auth | mockserver/mockserver-core/socket/tls/, mockserver-netty/unification/ | docs/code/tls-and-security.md |
| Configuration property (new flag / env var) | mockserver/mockserver-core/configuration/ + mockserver.example.properties + jekyll-www docs | docs/code/configuration-reference.md |
| Memory / ring buffer / log retention tuning | mockserver/mockserver-core/log/ + mockserver-core/mock/ | docs/code/memory-management.md |
| Event logging / verification / persistence | mockserver/mockserver-core/log/ + mockserver-core/persistence/ | docs/code/event-system.md |
| Dashboard UI (React/Redux) or live-feed protocol | mockserver-ui/ (TS) + mockserver-netty/web/ (server-side WebSocket) | docs/code/dashboard-ui.md |
| Java client API or JUnit/Spring integrations | mockserver/mockserver-client-java, mockserver-junit-*, mockserver-spring-test-listener | docs/code/client-and-integrations.md |
| Non-Java client (Python / Ruby / Node) | mockserver-client-python/, mockserver-client-ruby/, mockserver-client-node/ | docs/code/client-and-integrations.md |
| MCP / A2A mocking | Server handler: mockserver/mockserver-netty/src/main/java/org/mockserver/netty/mcp/. Builders: McpMockBuilder and A2aMockBuilder in mockserver/mockserver-client-java/src/main/java/org/mockserver/client/ | docs/code/ai-protocol-mocking.md |
| Build / Maven / dependency upgrade | mockserver/pom.xml + child poms + scripts/buildkite_*.sh | docs/operations/build-system.md, Java 17 floor in AGENTS.md |
| Docker image (server or CI base) | docker/, docker_build/ | docs/infrastructure/docker.md |
| Helm chart / Kubernetes deployment | helm/mockserver/, helm/mockserver-config/ | docs/infrastructure/helm.md |
| CI/CD pipeline (Buildkite, GitHub Actions) | .buildkite/, .github/workflows/ | docs/infrastructure/ci-cd.md |
| AWS infrastructure / Buildkite agents | terraform/buildkite-agents/, terraform/buildkite-pipelines/ | docs/infrastructure/aws-infrastructure.md |
| Release pipeline (per-component publish) | scripts/release/components/<component>.sh | docs/operations/release-process.md, docs/operations/release-principles.md |
| Consumer docs site | jekyll-www.mock-server.com/ | docs/operations/website.md |
Building
Java (main server)
cd mockserver && ./mvnw clean install
UI
cd mockserver-ui && npm ci && npm run build
Node.js client
cd mockserver-client-node && npm ci && npx grunt
Python client
cd mockserver-client-python
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/pytest
Ruby client
cd mockserver-client-ruby
bundle install
bundle exec rspec
Maven plugin
cd mockserver && ./mvnw clean install -DskipTests
./mvnw -f mockserver-maven-plugin/pom.xml clean verify
Contributions
Pull requests are welcome. Please:
- Open an issue first to discuss what you plan to change
- Follow existing code conventions in the module you are changing
- Add tests for any new functionality
- Ensure all tests pass before submitting
Opening a pull request shows a checklist template covering tests, changelog, docs, and the Java 17 / jakarta.* requirement — work through it before requesting review.
Feature Requests
Feature requests are submitted to GitHub issues and tracked on the project roadmap.