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
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.