--- title: Persisting Expectations description: Persist MockServer expectations and recorded proxy traffic to disk so they survive restarts and enable record-and-replay workflows. layout: page pageOrder: 7 section: 'Mock Server' subsection: true sitemap: priority: 0.8 changefreq: 'monthly' lastmod: 2019-11-10T08:00:00+01:00 ---

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.

  1. persistExpectations configuration property needs to be set to true
  2. the file path used to persist expectations can be configured using the persistedExpectationsPath configuration property
  3. 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-{{ site.mockserver_version }}-no-dependencies.jar -serverPort 1080,1081 -logLevel INFO

or

java \
-Dmockserver.persistExpectations=true \
-Dmockserver.persistedExpectationsPath=mockserverInitialization.json \
-Dmockserver.initializationJsonPath=mockserverInitialization.json \
-jar ~/Downloads/mockserver-netty-{{ site.mockserver_version }}-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.

  1. persistRecordedExpectations configuration property needs to be set to true
  2. the file path used to persist recorded expectations can be configured using the persistedRecordedExpectationsPath configuration property (default: persistedRecordedExpectations.json)
  3. 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-{{ site.mockserver_version }}-no-dependencies.jar -serverPort 1080,1081 -logLevel INFO

or

java \
-Dmockserver.persistRecordedExpectations=true \
-Dmockserver.persistedRecordedExpectationsPath=recordedExpectations.json \
-Dmockserver.initializationJsonPath=recordedExpectations.json \
-jar ~/Downloads/mockserver-netty-{{ site.mockserver_version }}-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.

{% include_subpage _includes/clustering.html %} {% include_subpage _includes/initializer_persistence_configuration.html %}