Skip to content

FastMock documentation

FastMock is an API mock server for test environments: HTTP, HTTPS with mTLS, gRPC, GraphQL, SOAP, WebSocket, Server-Sent Events, Kafka and AsyncAPI, with durable signed callbacks, shared state for any number of replicas, security by default and full observability. Start with Getting started, then pick the section for what you do.

Getting started

Page What you learn
Getting started Run FastMock with Docker or Docker Compose, create a token, first stub, journal, UI, callback and scenario in ten minutes.
Concepts Data plane and control plane, stubs, matching order, templates, state, journal, callbacks outbox, plugins, storage modes, replicas.
Web UI The admin UI at /ui and the Swagger UI for the admin API.

Writing mocks

Page What you learn
Request matching Every request condition: method, URL and path templates, query, headers, cookies, body matchers (JSON, XML, schema, multipart, form), logical operators, priorities, limits.
Responses Status, headers, bodies and body files, delays, dribbling, faults, response sequences, proxying.
Templating Handlebars context and every helper.
Stub lifecycle Ids, tags, metadata, enabling, times, expiry, counters, export.
Scenarios and state State machines, templated scenario names, TTLs, the key-value store.
Callbacks Webhooks after a response: delays, retries, HMAC signatures, correlation, egress policy.
Proxying and chaos rules Forward to real services; inject delays, errors and faults at random.
Server-Sent Events Event streams with per-event delays.
WebSocket Scripted WebSocket sessions.
gRPC Unary gRPC from uploaded descriptor sets.
GraphQL Matching GraphQL operations, schema import.
SOAP SOAP 1.1/1.2 stubs, WSDL and SoapUI import.
Kafka messages Publishing JSON or Avro records from stubs, Schema Registry, topic allow-list.
AsyncAPI and async mocks Mocks that keep publishing messages from AsyncAPI documents.

Importing and migrating

Page What you learn
Importing OpenAPI, Postman, HAR and auto-detection; common import options.
WireMock and MockServer import Field-by-field conversion of WireMock mappings and MockServer expectations.
Microcks artifacts OpenAPI with Microcks examples, APIExamples/APIMetadata, SoapUI, Postman, GraphQL, gRPC artifacts.
Service catalog The catalog of imported services and their operations.
Recording Recording real traffic and snapshots of the journal into stubs.
Migrating from WireMock Import, behaviour differences, test code changes.
Migrating from MockServer Import, behaviour differences, test code changes.
Migrating from Microcks Moving a Microcks installation's mocks to FastMock.

Testing with FastMock

Page What you learn
Verification Query the journal, verify counts and sequences, near misses.
Java client The Java 25 client: every method, JUnit 5 patterns, Testcontainers.
Contract testing Testing a real service against its OpenAPI or AsyncAPI contract.
Admin API Authentication, roles per endpoint, errors, pagination, every endpoint group.
Admin API reference Interactive Swagger UI for the admin API.
OpenAPI description Machine-readable description of the admin API (also served at /openapi.json).

Operating FastMock

Page What you learn
Configuration Every environment variable with type, default and effect.
Helm chart Install, upgrade, every value, production checklist, Gateway API, NetworkPolicy.
Operator MockServer and MockApi resources, status conditions, policies, RBAC, CRD upgrades.
Security Tokens and roles, origins, TLS, egress, secrets, redaction, limits, audit, hardening checklist.
Observability Every metric, PromQL examples, alerts, Grafana dashboard, tracing, logs, health checks.
Troubleshooting Symptom, cause and fix for the common problems.
Docker Compose example FastMock with PostgreSQL 18 and Valkey 9.

Reference

Page What you learn
Writing plugins Implement a provider in Rust and build a binary that includes it.
Security policy How to report a vulnerability.

Conventions in these pages

  • The data plane is http://localhost:8080 and the admin API http://localhost:9090; in Kubernetes they are the <release> and <release>-admin Services.
  • FASTMOCK_TOKEN holds an admin token (fastmock hash-token --generate); calls that change something need the editor role, a few need admin.
  • Example host names use example.com, example addresses 198.51.100.0/24 and 203.0.113.0/24.
  • Outputs shown on these pages come from real runs of FastMock 0.1.0, shortened where marked.