DOCSEARCHbyAlgolia
Submit Docs

MockServer Documentation

repository·master·Indexed 26 days ago

https://github.com/mock-server/mockserver-monorepo

An HTTP(S) mock server and proxy for testing, allowing developers to mock external APIs, record traffic, and perform chaos engineering by injecting failures and latency. The project includes a core Java server, a React dashboard UI, and client libraries for Java, Node.js, Python, and Ruby, with deployment options via Docker and Helm charts.

Tokens
247.4K
Snippets
392
Records
1.2K
Agent score
88%

What's inside MockServer

  1. Overview of the OpenCode 7 Building Blocks

    master

    The OpenCode harness is structured into seven distinct layers located within the .opencode/ directory and the repository root. These layers teach the AI assistant about MockServer's specific boundaries, conventions, and infrastructure:

    1. Config (opencode.jsonc): Root configuration for models, permissions, and agents.
    2. Model Strategy (opencode.jsonc): Assigns the right model to the right task.
    3. Agents (.opencode/agents/*.md): Specialist sub-agents with least-privilege access.
    4. Rules (.opencode/rules/*.md): Guardrails that are always enforced.
    5. Skills (.opencode/skills/*/SKILL.md): Reusable multi-step workflows.
    6. Commands (.opencode/commands/*.md): Slash shortcuts for routing tasks.
    7. Plugins & Tools (.opencode/plugins/*.ts): Session hooks and external integrations.

  2. Overview of MockServer AWS Infrastructure

    master

    MockServer infrastructure is divided into two distinct AWS accounts to separate build processes from website hosting:

    1. Build Agent Account: Manages the CI/CD pipeline, including Buildkite agents, Auto Scaling Groups (ASG) for different queues (default, trigger, and performance), Lambda autoscalers, and storage for build results and secrets.
    2. Website Account: Manages the public-facing website, including S3 buckets for hosting, CloudFront distributions for CDN, Route53 for DNS, and ACM for TLS certificates.

    The build agent account utilizes a VPC with public subnets and VPC endpoints for private access to services like SSM and EC2 Messages.

  3. Overview of the Async Messaging Module (mockserver-async)

    master

    The mockserver-async module enables message-broker mocking driven by AsyncAPI 2.x or 3.x specifications. It parses AsyncAPI documents to generate schema-validated example payloads, which it then publishes to a message broker. Additionally, it can subscribe to channels to record incoming messages for verification.

    Supported Brokers

    • Kafka: Supports JSON (default) and Avro in the Confluent Schema Registry wire format (magic byte + schema id + Avro binary). Avro can operate in registry-backed mode (using a Schema Registry URL) or registry-less mode (fixed schema id + inline schema).
    • MQTT: Supports MQTT 3.1.1 (default) and MQTT 5 (via mqttProtocolVersion: 5). MQTT 5 adds support for user-property (header) delivery.
    • AMQP 0.9.1 (RabbitMQ): Supports publishing and subscribing using exchange/routing key bindings defined in the AsyncAPI spec.

  5. Overview of MockServer Monorepo Structure

    master

    MockServer is a monorepo containing the Java server, client libraries, UI, plugins, and infrastructure. The project is organized into several key areas:

    • mockserver/: The Java server (multi-module Maven project) containing the core engine, Netty-based server, client libraries, and various integrations (JUnit, Spring, Testcontainers, etc.).
    • examples/: Runnable usage examples for Java, Node.js, Python, Ruby, Curl, JSON, Docker Compose, WASM, and Chaos engineering.
    • mockserver-ui/: A React-based dashboard UI built with Vite and TypeScript.
    • mockserver-node/: A Node.js launcher for MockServer.
    • mockserver-client-node/: A client library for Node.js and browsers.
    • mockserver-client-python/: A Python client library.
    • mockserver-client-ruby/: A Ruby client library.
    • helm/: Helm charts for deploying MockServer and its configuration.
    • docker/: Production-ready Docker images (5 variants available).

  6. Overview of the MockServer Dashboard UI

    master
    The MockServer Dashboard is a React-based web application used to monitor, manage, and interact with the MockServer instance in real-time. It provides a visual interface for viewing logs, active expectations, recorded requests, and proxied traffic. The UI uses WebSockets for real-time updates and supports various specialized views like a 'Composer' for creating mocks and 'Session Inspector' for LLM conversations.

  7. Overview of MockServer Project Structure

    master

    The MockServer monorepo is organized into several key components:

    • mockserver/: The core Java server (Maven project) containing:
      • mockserver-core: Domain model, matching, and serialization.
      • mockserver-client-java: Java client library.
      • mockserver-netty: The main Netty-based HTTP server artifact.
      • mockserver-war / mockserver-proxy-war: WAR-packaged versions.
      • mockserver-junit-rule / mockserver-junit-jupiter: JUnit 4 and 5 integrations.
      • mockserver-spring-test-listener: Spring test integration.
    • mockserver-ui/: React dashboard UI.
    • mockserver-node/: Node.js launcher (npm).
    • mockserver-client-node/: Node.js/browser client library (npm).
    • mockserver-client-python/: Python client library (PyPI).
    • mockserver-client-ruby/: Ruby client library (RubyGems).
    • examples/: Runnable examples in various languages (Java, Node, Python, Ruby, Curl, JSON, Docker-compose, WASM, Chaos).
    • helm/: Helm charts for deployment.
    • docker/: Production Docker images.

  8. Overview of MockServer Helm Charts

    master

    MockServer provides two Helm charts for Kubernetes deployment:

    1. mockserver: The main deployment chart. It can optionally create its own ConfigMap using inline configuration or mount an externally-created ConfigMap to the /config volume.
    2. mockserver-config: A legacy/reference chart used to demonstrate how to create an external ConfigMap containing mockserver.properties and initializerJson.json.
    ChartPathVersionPurpose
    mockserverhelm/mockserver/7.4.0Main deployment chart (includes optional ConfigMap)
    mockserver-confighelm/mockserver-config/7.4.0Example external ConfigMap chart (for reference)

  9. Overview of MockServer Deployment Options

    master

    MockServer is an HTTP(S) mock server and proxy built on Netty 4.2. It can be deployed in several ways depending on your testing needs:

    • Standalone: Run as a standalone JAR or via Docker containers.
    • Servlet Containers: Deploy as a WAR file (mockserver-war) or a proxy-only WAR (mockserver-proxy-war) in environments like Tomcat or Jetty.
    • Embedded/Integrated: Use JUnit 4 (mockserver-junit-rule), JUnit 5 (mockserver-junit-jupiter), or Spring (mockserver-spring-test-listener) to manage the server lifecycle within your test suites.
    • Kubernetes: Use the mockserver-k8s-webhook for automatic sidecar injection into pods.

  10. Overview of Build Agent AWS Infrastructure

    master
    The MockServer build agent infrastructure is hosted in the eu-west-2 region and is managed via Terraform located in terraform/buildkite-agents/. The architecture uses an automated scaling system driven by Buildkite queue depth to manage EC2 instances across different Auto Scaling Groups (ASGs) for various job types (default, trigger, release, and perf).

  11. Overview of MockServer Editor Extensions

    master

    MockServer provides IDE extensions for VS Code and JetBrains to bring MockServer controls directly into your development environment.

    Key capabilities include:

    • Schema Validation: Automatic validation, completion, and hover support for *.mockserver.json files using a built-in JSON schema.
    • REST Integration: Both extensions communicate with a running MockServer instance over its REST API.
    • No Language Server Required: Validation and completion are handled by the editors' native JSON engines via the mockserver-expectation.schema.json.

    Compatibility Note:

    • VS Code: Published to VS Code Marketplace and Open VSX (publisher: mockserver).
    • JetBrains: Targets IntelliJ Community (platformType=IC) since build 243 (2024.3).

  12. Overview of MockServer Testing Strategy

    master

    MockServer employs a multi-layered testing strategy to ensure reliability across different environments. The testing hierarchy includes:

    1. Unit Tests: Focused on individual components (matchers, serialization, etc.), primarily using JUnit 4.
    2. Integration Tests: Exercise full request/response flows using real servers (Netty, embedded Tomcat).
    3. Packaging Verification: Ensures published artifacts (Maven/Gradle) work correctly in downstream projects.
    4. Container Integration: Tests involving Docker Compose and Helm/k3d.
    5. Performance Tests: Conducted using k6.