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-6.1.0-no-dependencies.jar -serverPort 1080,1081 -logLevel INFO

java \
-Dmockserver.persistExpectations=true \
-Dmockserver.persistedExpectationsPath=mockserverInitialization.json \
-Dmockserver.initializationJsonPath=mockserverInitialization.json \
-jar ~/Downloads/mockserver-netty-6.1.0-no-dependencies.jar -serverPort 1080,1081 -logLevel INFO

Persisting 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-6.1.0-no-dependencies.jar -serverPort 1080,1081 -logLevel INFO

java \
-Dmockserver.persistRecordedExpectations=true \
-Dmockserver.persistedRecordedExpectationsPath=recordedExpectations.json \
-Dmockserver.initializationJsonPath=recordedExpectations.json \
-jar ~/Downloads/mockserver-netty-6.1.0-no-dependencies.jar -serverPort 1080,1081 -logLevel INFO

This 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/mockserver

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

Clustering MockServer

MockServer supports a very high request throughput, however if a higher request per second rate is required it is possible to cluster MockServer so that all nodes share expectations.

Although expectations are clustered, currently there is no support for clustering the MockServer log therefore request verifications will only work against the node that received the request.

To create a 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-6.1.0-no-dependencies.jar -serverPort 1080 -logLevel INFO

java \
-Dmockserver.watchInitializationJson=true \
-Dmockserver.initializationJsonPath=mockserverInitialization.json \
-Dmockserver.persistExpectations=true \
-Dmockserver.persistedExpectationsPath=mockserverInitialization.json \
-jar ~/Downloads/mockserver-netty-6.1.0-no-dependencies.jar -serverPort 1080 -logLevel INFO

Initialization & 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"