Persisting Expectations
In MockServer expectations are only held in memory by default. However, it is possible to persist expectations to the local file system to ensure that they survive a restart of MockServer.
- persistExpectations configuration property needs to be set to true
- the file path used to persist expectations can be configured using the persistedExpectationsPath configuration property
- expectations should be initialised automatically using the initializationJsonPath configuration property
To ensure that the persisted expectations are loaded the next time MockServer starts the initializationJsonPath and persistedExpectationsPath should match and the persistExpectations should be set to true as follows:
MOCKSERVER_PERSIST_EXPECTATIONS=true \
MOCKSERVER_PERSISTED_EXPECTATIONS_PATH=mockserverInitialization.json \
MOCKSERVER_INITIALIZATION_JSON_PATH=mockserverInitialization.json \
java -jar ~/Downloads/mockserver-netty-7.1.0-no-dependencies.jar -serverPort 1080,1081 -logLevel INFOor
java \
-Dmockserver.persistExpectations=true \
-Dmockserver.persistedExpectationsPath=mockserverInitialization.json \
-Dmockserver.initializationJsonPath=mockserverInitialization.json \
-jar ~/Downloads/mockserver-netty-7.1.0-no-dependencies.jar -serverPort 1080,1081 -logLevel INFOPersisting Recorded Proxy Expectations
When MockServer acts as a proxy, all forwarded requests are automatically recorded as expectations. These recorded expectations can be persisted to a file that is updated each time a new request is forwarded. This enables a record-and-replay workflow where traffic is captured from a real system and then replayed as mock expectations.
- persistRecordedExpectations configuration property needs to be set to true
- the file path used to persist recorded expectations can be configured using the persistedRecordedExpectationsPath configuration property (default: persistedRecordedExpectations.json)
- to replay recorded expectations on restart, set initializationJsonPath to the same file path
MOCKSERVER_PERSIST_RECORDED_EXPECTATIONS=true \
MOCKSERVER_PERSISTED_RECORDED_EXPECTATIONS_PATH=recordedExpectations.json \
MOCKSERVER_INITIALIZATION_JSON_PATH=recordedExpectations.json \
java -jar ~/Downloads/mockserver-netty-7.1.0-no-dependencies.jar -serverPort 1080,1081 -logLevel INFOor
java \
-Dmockserver.persistRecordedExpectations=true \
-Dmockserver.persistedRecordedExpectationsPath=recordedExpectations.json \
-Dmockserver.initializationJsonPath=recordedExpectations.json \
-jar ~/Downloads/mockserver-netty-7.1.0-no-dependencies.jar -serverPort 1080,1081 -logLevel INFOThis is separate from the persistExpectations property which persists manually-created expectations. Both can be enabled simultaneously with different file paths.
Kubernetes Persistence
On Kubernetes, pods are ephemeral — any files written inside the container are lost when the pod restarts. To persist expectations across pod restarts, the MockServer Helm chart supports PersistentVolumeClaims.
The simplest way to enable persistence on Kubernetes is:
helm upgrade --install --namespace mockserver \
--set app.persistence.enabled=true \
mockserver helm/mockserverThis creates a PersistentVolumeClaim and automatically configures MockServer to persist and reload expectations from it. No additional configuration is needed.
For clustered deployments on Kubernetes, use a ReadWriteMany PVC backed by a shared filesystem (e.g. NFS, AWS EFS, or Azure Files). See the Helm chart persistent storage documentation for full details and examples.
Cloud Blob Storage
By default MockServer reads and writes persisted expectations, recorded proxy traffic, and fixture files on the local filesystem (blobStoreType=filesystem). When several nodes — or several short-lived CI runners — need durable, shared storage of this data without a shared POSIX volume (NFS / EFS / Azure Files), MockServer can store it in a cloud object store instead.
Cloud blob storage is an opt-in module: mockserver-core ships with no cloud SDK on its classpath, so there is no dependency cost unless you use it. Add the module for the backend you want and set blobStoreType to its name — the backend registers itself automatically at startup.
| blobStoreType | Backend | Maven module |
|---|---|---|
| s3 | Amazon S3 (and S3-compatible stores such as MinIO / LocalStack) | org.mock-server:mockserver-blob-s3 |
| gcs | Google Cloud Storage | org.mock-server:mockserver-blob-gcs |
| azure | Azure Blob Storage | org.mock-server:mockserver-blob-azure |
The key required properties per backend are:
- S3 (blobStoreType=s3): blobStoreBucket and blobStoreRegion. Credentials default to the standard AWS credential chain (environment, profile, instance/IRSA role); override explicitly with blobStoreAccessKeyId / blobStoreSecretAccessKey. Use blobStoreEndpoint to target an S3-compatible store such as MinIO or LocalStack.
- GCS (blobStoreType=gcs): blobStoreBucket. Credentials default to Application Default Credentials; set blobStoreProjectId to override the inferred project.
- Azure (blobStoreType=azure): blobStoreContainer and blobStoreConnectionString (the connection string carries the account name, key, and endpoint).
An optional blobStoreKeyPrefix applies to all cloud backends so multiple deployments can share one bucket or container without colliding.
Example (S3) running the Docker image — note that you must use an image with the relevant mockserver-blob-* module (and its cloud SDK) on the classpath:
MOCKSERVER_BLOB_STORE_TYPE=s3 \
MOCKSERVER_BLOB_STORE_BUCKET=my-mockserver-fixtures \
MOCKSERVER_BLOB_STORE_REGION=eu-west-1 \
MOCKSERVER_BLOB_STORE_KEY_PREFIX=ci-shared/ \
MOCKSERVER_PERSIST_EXPECTATIONS=true \
java -jar mockserver-netty-jar-with-dependencies.jar -serverPort 1080 -logLevel INFOSee Configuration Properties for the full property list with defaults, and Centralised Deployment → Cloud Blob Storage for using a blob store across a shared or clustered deployment.
Clustering MockServer
MockServer supports a very high request throughput from a single node. When you need high availability, horizontal scale beyond one node, or zero-downtime rolling updates, MockServer can run as a cluster so that all nodes share state.
There are two ways to cluster MockServer. For the full deployment guide — architecture diagrams, the -clustered image, Docker Compose and Helm examples, and a decision table — see Centralised Deployment.
Infinispan state backend (recommended)
The production-grade approach uses an embedded Infinispan state backend that replicates state synchronously across all nodes over JGroups. Expectations, scenario state, CRUD entity stores, and chaos profiles are visible on every node immediately after any write, and per-expectation Times match limits are enforced cluster-wide. No shared filesystem is required.
Clustering requires the mockserver-state-infinispan module on the classpath. The pre-built -clustered Docker image (mockserver/mockserver:clustered-7.1.0) bundles this module and its JGroups dependencies; the default image does not. It is enabled with three properties:
| Property | Env var | Default | Description |
|---|---|---|---|
| mockserver.stateBackend | MOCKSERVER_STATE_BACKEND | memory | Set to infinispan to enable the clustered backend (requires the mockserver-state-infinispan module). |
| mockserver.clusterEnabled | MOCKSERVER_CLUSTER_ENABLED | false | Set to true to activate the JGroups transport and state replication across nodes. |
| mockserver.clusterName | MOCKSERVER_CLUSTER_NAME | mockserver-cluster | Cluster identifier. All nodes that should share state must use the same value. |
Note: as with the file-based approach below, the request log and verification ring buffer are node-local — a verify() call only checks the node that received it. The Centralised Deployment page covers this constraint and the full Docker Compose and Kubernetes/Helm setup.
Shared filesystem (simpler alternative)
A simpler alternative that needs no extra module is to have several non-clustered nodes share their expectations through a common read-write filesystem and identical persistence configuration. State is reconciled by writing to and re-reading the shared file rather than by live replication, so propagation is eventual rather than synchronous. This suits modest fleets where a shared volume is already available.
To create a file-based MockServer cluster all instances need to:
- share a read-write file system i.e. same physical / virtual machine, NFS, AWS EFS, Azure Files, etc
- configure identical expectation initialiser and expectation persistence
- bind to a free port i.e. separate ports if on same physical / virtual machine
Each node could be configured as follows (adjusting the port as necessary):
MOCKSERVER_WATCH_INITIALIZATION_JSON=true \
MOCKSERVER_INITIALIZATION_JSON_PATH=mockserverInitialization.json \
MOCKSERVER_PERSIST_EXPECTATIONS=true \
MOCKSERVER_PERSISTED_EXPECTATIONS_PATH=mockserverInitialization.json \
java -jar ~/Downloads/mockserver-netty-7.1.0-no-dependencies.jar -serverPort 1080 -logLevel INFOor
java \
-Dmockserver.watchInitializationJson=true \
-Dmockserver.initializationJsonPath=mockserverInitialization.json \
-Dmockserver.persistExpectations=true \
-Dmockserver.persistedExpectationsPath=mockserverInitialization.json \
-jar ~/Downloads/mockserver-netty-7.1.0-no-dependencies.jar -serverPort 1080 -logLevel INFOInitialization & Persistence Configuration:
The class (and package) used to initialize expectations in MockServer at startup, if set MockServer will load and call this class to initialise expectations when is starts.
Type: string Default: null
Java Code:
ConfigurationProperties.initializationClass(String initializationClass)System Property:
-Dmockserver.initializationClass=...Environment Variable:
MOCKSERVER_INITIALIZATION_CLASS=...Property File:
mockserver.initializationClass=...Spring @MockServerTest:
@MockServerTest("mockserver.initializationClass=org.mockserver.server.initialize.ExpectationInitializerExample")Example:
-Dmockserver.initializationClass="org.mockserver.server.initialize.ExpectationInitializerExample"The path to the json file used to initialize expectations in MockServer at startup, if set MockServer will load this file and initialise expectations for each item in the file when is starts.
The expected format of the file is a JSON array of expectations, as per the REST API format
Type: string Default: null
Java Code:
ConfigurationProperties.initializationJsonPath(String initializationJsonPath)System Property:
-Dmockserver.initializationJsonPath=...Environment Variable:
MOCKSERVER_INITIALIZATION_JSON_PATH=...Property File:
mockserver.initializationJsonPath=...Example:
-Dmockserver.initializationJsonPath="org/mockserver/server/initialize/initializerJson.json"The path to the OpenAPI spec file used to initialize expectations in MockServer at startup, if set MockServer will load this file and create expectations for each operation when it starts.
The file can be a YAML (.yaml, .yml) or JSON (.json) OpenAPI v3 specification. MockServer will generate an expectation for each operation defined in the spec, with example responses derived from the schema.
To watch multiple files use file globs as documented here: glob patterns
Type: string Default: null
Java Code:
ConfigurationProperties.initializationOpenAPIPath(String initializationOpenAPIPath)System Property:
-Dmockserver.initializationOpenAPIPath=...Environment Variable:
MOCKSERVER_INITIALIZATION_OPENAPI_PATH=...Property File:
mockserver.initializationOpenAPIPath=...Example:
-Dmockserver.initializationOpenAPIPath="/config/petstore.yaml"If enabled the initialization JSON file and OpenAPI file will be watched for changes, any changes found will result in expectations being created, removed or updated by matching against their key.
If duplicate keys exist only the last duplicate key in the file will be processed and all duplicates except the last duplicate will be removed.
The order of expectations in the file is the order in which they are created if they are new, however, re-ordering existing expectations does not change the order they are matched against incoming requests.
Type: boolean Default: false
Java Code:
ConfigurationProperties.watchInitializationJson(boolean enable)System Property:
-Dmockserver.watchInitializationJson=...Environment Variable:
MOCKSERVER_WATCH_INITIALIZATION_JSON=...Property File:
mockserver.watchInitializationJson=...Example:
-Dmockserver.watchInitializationJson="false"Enable the persisting of expectations as json, which is updated whenever the expectation state is updated (i.e. add, clear, expires, etc)
Type: boolean Default: false
Java Code:
ConfigurationProperties.persistExpectations(boolean persistExpectations)System Property:
-Dmockserver.persistExpectations=...Environment Variable:
MOCKSERVER_PERSIST_EXPECTATIONS=...Property File:
mockserver.persistExpectations=...Example:
-Dmockserver.persistExpectations="true"The file path used to save persisted expectations as json, which is updated whenever the expectation state is updated (i.e. add, clear, expires, etc)
Type: string Default: persistedExpectations.json
Java Code:
ConfigurationProperties.persistedExpectationsPath(String persistedExpectationsPath)System Property:
-Dmockserver.persistedExpectationsPath=...Environment Variable:
MOCKSERVER_PERSISTED_EXPECTATIONS_PATH=...Property File:
mockserver.persistedExpectationsPath=...Example:
-Dmockserver.persistedExpectationsPath="org/mockserver/server/initialize/initializerJson.json"Enable the persisting of recorded expectations (proxy traffic) as json, which is updated whenever a new request is forwarded through the proxy.
The persisted file can be loaded on restart using initializationJsonPath to replay recorded traffic as mock expectations.
Type: boolean Default: false
Java Code:
ConfigurationProperties.persistRecordedExpectations(boolean enable)System Property:
-Dmockserver.persistRecordedExpectations=...Environment Variable:
MOCKSERVER_PERSIST_RECORDED_EXPECTATIONS=...Property File:
mockserver.persistRecordedExpectations=...Example:
-Dmockserver.persistRecordedExpectations="true"The file path used to save persisted recorded expectations as json, which is updated whenever a new request is forwarded through the proxy.
Type: string Default: persistedRecordedExpectations.json
Java Code:
ConfigurationProperties.persistedRecordedExpectationsPath(String persistedRecordedExpectationsPath)System Property:
-Dmockserver.persistedRecordedExpectationsPath=...Environment Variable:
MOCKSERVER_PERSISTED_RECORDED_EXPECTATIONS_PATH=...Property File:
mockserver.persistedRecordedExpectationsPath=...Example:
-Dmockserver.persistedRecordedExpectationsPath="recordedExpectations.json"Verification Configuration:
The maximum number of requests to return in verification failure result, if more expectations are found the failure result does not list them separately
Type: int Default: 10
Java Code:
ConfigurationProperties.maximumNumberOfRequestToReturnInVerificationFailure(Integer maximumNumberOfRequestToReturnInVerificationFailure)System Property:
-Dmockserver.maximumNumberOfRequestToReturnInVerificationFailure=...Environment Variable:
MOCKSERVER_MAXIMUM_NUMBER_OF_REQUESTS_TO_RETURN_IN_VERIFICATION_FAILURE=...Property File:
mockserver.maximumNumberOfRequestToReturnInVerificationFailure=...Example:
-Dmockserver.maximumNumberOfRequestToReturnInVerificationFailure="20"Related Pages
- Initializing Expectations — reload persisted expectations automatically when MockServer starts
- File Storage — the in-memory file store REST API (PUT /mockserver/files/...) for uploading and retrieving named fixture files at runtime — distinct from on-disk expectation persistence
- Creating Expectations — the structure of the expectations being persisted: request matchers and response, forward, callback, and error actions