Skip to main content
View as Markdown

keploy.yml and keploy.lock​

A project that uses the Universal Mocker commits two small files:

  • keploy.yml says how Keploy runs your tests and where their recordings live.
  • keploy.lock names the exact recordings that keploy mock replay serves, the way go.sum names the exact modules of go.mod.

By default the recordings themselves live in Keploy Cloud, so git holds only these two files. Each commit replays exactly the recordings its keploy.lock names.

keploy.lock is part of Keploy's proven model: the commands on this page that read or write it run only with KEPLOY_PROVEN=1 set. Without it, Keploy refuses them and names the variable to set.

What to commit​

Where the recordings liveCommitKeploy keeps out of git
Keploy Cloud (the default)keploy.yml and keploy.lock.keploy-run/, the run files of each record and replay: its own .gitignore holds *.
In the repository (mock.local: true, or --local)keploy.yml and keploy/, with keploy/.gitignore as writtenThe same .keploy-run/, and the run files that keploy/.gitignore lists.

Commit keploy.lock with the change its recordings go with, as you commit go.sum with go.mod. A pull request that re-records tests then shows, in its diff, which tests now replay on new recordings.

keploy.yml​

keploy.yml sits at the root of the project. Run keploy mock there, or pass --config-path <folder> to name the folder that holds it.

The Universal Mocker reads the keys under mock:. A typical project needs only command, and appId once it records to Keploy Cloud:

mock:
command: go test -p 1 -count=1 -json ./...
appId: <your app id>

The keys under mock: that most projects use:

KeyWhat it does
commandThe command that runs your tests, as CI runs it. With KEPLOY_PROVEN=1, keploy mock record and keploy mock replay run it when you don't pass -c.
appIdThe Keploy app that holds the recordings. keploy app create writes it (below).
nameThe mock set to record into and replay from, as --name sets it.
localtrue keeps the recordings in the repository, under keploy/<set>/, as --local does. No keploy.lock is read or written.
branchThe Keploy branch to read and publish when no keploy.lock pins the recordings. Ignored while a lock pins them.
onMissWhat replay does with a call that matches no recording: fail (the default), passthrough or record, as --on-miss sets it.
strictFail the replay when a call missed its recording, even when the tests passed, as --strict does.
realDestinations that every run reaches for real, never recorded and never mocked, such as localhost:5432 or container:redis. Read only with KEPLOY_PROVEN=1.

Save the app's id​

Run this once in the project, signed in (keploy login) or with KEPLOY_API_KEY set:

keploy app create --name <app name>

It creates the Keploy app, or reuses the one with that name, and saves its id as mock.appId in keploy.yml. Without --name, it names the app after the git repository.

created app docs-lock-guide (<app id>)

keploy.yml then reads:

mock:
command: go test -p 1 -count=1 -json ./...
appId: <app id>
appName: docs-lock-guide

Commit keploy.yml before you record: a record made from uncommitted changes says so, because its recording matches the code only once those changes are committed.

--app <name> on keploy mock record also creates or reuses an app, but only for that command: it does not save the id. A later command without --app or mock.appId looks for an app named after the repository instead.

keploy.lock​

What it pins​

For each mock set, the lock names one recording for each test and one for the set's start-up: the calls made outside every test, such as in Go's TestMain. Each recording is named by the sha256 digest of its bytes, like an image digest, so a recording cannot change under the lock.

This is the keploy.lock of a Go project with two tests, TestTotalInUSD and TestTotalInEUR:

# keploy.lock: the recordings `keploy mock replay` serves for this project, one immutable
# recording per test, named by its sha256 (like an image digest). Written by `keploy mock record`:
# commit it with your change. A `skip:` line under an entry is a test keploy does not replay,
# and why; it applies only while it names its entry's digest, so a re-record runs the test again.
# To skip a test, quarantine it (`keploy mock quarantine`); deleting its entry does not.
# Never edit a digest: replay refuses one it cannot verify.
version: 1

.::@startup:
digest: sha256:10d66037d20bd706d718560edc3a3fd884f462bcfc6f5be81be037186434eb36 # 2026-11-20T03:07Z linux keploy 3.9.4 at 5c5e4335d81a

.::.::TestTotalInEUR:
digest: sha256:314c6639e8682100b87dee680397237c9ed4098b0b19dc59964c7757b5b66ad4 # 2026-11-20T03:07Z linux keploy 3.9.4 at 5c5e4335d81a

.::.::TestTotalInUSD:
digest: sha256:38f35de415d243c9c4d1f6d2687e63f8c62a2a9d6577cfdf9b0f886ca6a3fbed # 2026-11-20T03:07Z linux keploy 3.9.4 at 5c5e4335d81a

Each entry names a test, and the @startup entry the set's start-up. The comment after a digest says when, on which OS, with which Keploy version and at which commit the recording was made. Keploy does not read it.

  • keploy mock replay serves the recordings the lock names. It does not read the copies in the set's folder under keploy/.
  • A skip: line under an entry is a test Keploy does not replay, and the reason. It applies only while it names its entry's digest, so a re-record runs the test again.
  • To skip a test, quarantine it with keploy mock quarantine. Deleting its entry does not skip it.
  • Never edit a digest by hand: replay refuses a recording it cannot verify.

Where it lives​

The lock sits next to the project's keploy.yml. Every keploy mock command that reads or writes it uses that file by default, and keploy mock record writes it.

To make a project's first lock, or to use a lock somewhere else, pass --lock. A --lock path that does not exist yet is created:

KEPLOY_PROVEN=1 keploy mock record --lock keploy.lock

When the record ends, its last lines say what it pinned:

keploy: keploy.lock: re-recorded .::.::TestTotalInEUR, .::.::TestTotalInUSD (2), kept 0, start-up re-recorded; recordings 3 uploaded, 0 already on the server; packs 3 uploaded, 0 already on the server
keploy: commit keploy.lock with your change
keploy: keploy.lock is not listed in Keploy Cloud: the pin of app <app id> is off, so its replays read Keploy branches, which a listed one could change; `KEPLOY_PROVEN=1 keploy mock pin on` turns it on, then `KEPLOY_PROVEN=1 keploy mock register` lists the lock
keploy: committed keploy/orders and its skip lines (pinned in keploy.lock): 2 replayable, 0 quarantined

In this mode the recordings are in Keploy Cloud, so git status shows only the new keploy.lock. Commit it.

Later records and replays find keploy.lock by themselves.

Turn on the app's recording pin​

Once keploy.lock is committed, turn on the app's recording pin. While it is on, every replay of the app reads keploy.lock, Keploy Cloud serves a Keploy branch's recordings only to a replay that names the branch with --branch, and a Keploy too old to read keploy.lock fails instead of replaying a branch. A CI key cannot turn the pin: sign in as a person.

KEPLOY_PROVEN=1 keploy mock pin on
The pin of app <app id> is on: Keploy Cloud now serves its Keploy branches only to a replay that names one (--branch), so every other keploy mock replay of it reads the project's keploy.lock, and a keploy too old to read keploy.lock fails instead of replaying a branch.

Then list the lock under your git branch, for the dashboard's Recordings and Branch reviews. While the pin is on, later records and publishes list it by themselves:

KEPLOY_PROVEN=1 keploy mock register
keploy: listed keploy.lock in Keploy Cloud under branch add-lock (3 recorded, 0 removed, 0 unchanged): https://app.keploy.io/recordings?appId=<app id>&view=e2e&branch=add-lock

keploy mock pin status shows the pin, and keploy mock pin off turns it off.

Replay what the lock pins​

With the dependencies off, replay reads the lock, pulls the recordings it names, and runs the tests on them:

KEPLOY_PROVEN=1 keploy mock replay
INFO  pulled set "orders" pinned by /work/orders/keploy.lock: 2 tests, 0 cases; recordings 3 fetched, 0 cached, 0 skipped by keploy.lock and not fetched; packs 3 fetched, 0 cached
...
keploy: orders: 2 test(s) ran: 2 passed, 0 failed (0 held by keploy), 0 skipped by the test; 0 quarantined (skipped by keploy)
VERDICT passed

The lock and Keploy branches​

  • --lock does not go with --branch: Keploy refuses the pair, because they name two sources of recordings.
  • --branch alone reads the Keploy branch it names, even when there is a keploy.lock, and says that it does. In Keploy 3.9.4, a replay of a branch that keploy mock register listed leaves out the branch's start-up recording, so a test whose code connects to a database fails with FAILED_BY_KEPLOY on a connection-startup miss. Replay from the lock instead: run KEPLOY_PROVEN=1 keploy mock replay without --branch.
  • While a lock pins the recordings, Keploy ignores keploy.yml's mock.branch and says so.
  • --local, or mock.local: true, keeps the recordings in the repository instead, and no lock is read or written.

What each case prints:

  • Without KEPLOY_PROVEN=1, in a project that has a keploy.lock:

    Error: /work/orders/keploy.lock pins this project's recordings, which keploy mock reads only with KEPLOY_PROVEN=1: set it, or pass --branch <name> to read a Keploy branch
  • --lock without KEPLOY_PROVEN=1:

    Error: keploy mock record --lock is part of the proven model and runs only with KEPLOY_PROVEN=1, which is not set here: run KEPLOY_PROVEN=1 keploy mock record --lock keploy.lock
  • --branch with --lock:

    Error: --branch add-lock and --lock /work/orders/keploy.lock name two sources of recordings: pass one
  • --branch alone, in a project that has a keploy.lock:

    WARN  reading the Keploy branch --branch names, not keploy.lock  {"branch": "add-lock", "lock": "/work/orders/keploy.lock"}

    In 3.9.4 that replay of the branch keploy mock register listed then goes red, because the start-up recording is missing:

    INFO  pulled set "orders" from branch "add-lock": 2 tests, 0 cases; packs 2 fetched  {"mock-set": "orders"}
    INFO mock replay summary {"loaded": 6, "consumed": 0, "missed": 2}
    FAILED_BY_KEPLOY .::TestTotalInEUR (failed): keploy/unmocked_call
    MISS PostgreSQL connection startup to [::1]:5432 x1 match stopped at no_mocks
  • mock.branch set while a lock pins the recordings:

    WARN  keploy.yml's mock.branch is ignored: keploy.lock pins the recordings  {"mock.branch": "some-branch", "lock": "/work/orders/keploy.lock"}

Publish a staged recording​

A keploy mock record that judged its tests keeps its recording in a staging folder under the project's .keploy-run/staging/ when its own publish fails. keploy mock judge keeps a mapping edit that it judged there too. Each prints the line that publishes what it kept. Run that line:

KEPLOY_PROVEN=1 keploy mock publish --from .keploy-run/staging/<folder>

For example, a record whose keploy.yml had lost its mock.appId judged its tests but could not publish them:

keploy: keploy/orders is judged, but its recording was not published (no Keploy app: run "keploy app create" or pass --app <name>); it is kept in /work/orders/.keploy-run/staging/20261120T030817Z-2396317157, and keploy.lock is unchanged. Publish it with: KEPLOY_PROVEN=1 keploy mock publish --from /work/orders/.keploy-run/staging/20261120T030817Z-2396317157
keploy: judged keploy/orders, not published: 2 replayable, 0 quarantined

With mock.appId back in keploy.yml, the printed line publishes the recording and pins it:

KEPLOY_PROVEN=1 keploy mock publish --from /work/orders/.keploy-run/staging/20261120T030817Z-2396317157
keploy: keploy.lock: re-recorded .::.::TestTotalInEUR, .::.::TestTotalInUSD (2), kept 0, start-up re-recorded; recordings 3 uploaded, 0 already on the server; packs 3 uploaded, 0 already on the server
keploy: recorded from uncommitted changes in 1 file(s); the recording matches the code only once you commit them with keploy.lock
keploy: commit keploy.lock with your change
keploy: listed keploy.lock in Keploy Cloud under branch add-lock (3 recorded, 0 removed, 0 unchanged): https://app.keploy.io/recordings?appId=<app id>&view=e2e&branch=add-lock

git diff keploy.lock then shows a new digest on each entry, and the staging folder is gone.

The publish uploads the recording to Keploy Cloud. In a project that a lock pins, it pins the recording and its skip lines in the lock; otherwise it writes the judged verdicts.yaml into the project. Then it removes the staging folder.

If the record or judge was given a --lock other than the project's own keploy.lock, the line it prints names that lock with --lock, and the publish pins the recording only there:

KEPLOY_PROVEN=1 keploy mock publish --from .keploy-run/staging/<folder> --lock ci/keploy.lock

--lock goes only with --from. Without --lock, the publish pins only in the project's own keploy.lock.

When the publish refuses​

keploy mock publish --from writes only into the project whose .keploy-run holds the staging folder. It refuses, says why, and publishes nothing when:

  • the folder is not a staging folder a record kept, or it is not in a Keploy project's .keploy-run: there is no keploy.yml that sets mock.command in the folder that holds .keploy-run;
  • the staged recording names a keploy folder other than the one the project's keploy.yml names;
  • the staged recording pins in a lock other than the project's own and --lock does not name it, or --lock names a lock other than the staged one;
  • .keploy-run, the staging folder or a folder in it is a symbolic link that leads out of the project;
  • it is a judged mapping edit whose judge left a test failing with no skip line, or said CI's run of the set would be red. The refusal names each test and what to do about it: quarantine it, make the edit its line names, or record it again. Then run keploy mock judge again and publish what it stages.

Two of these, as printed:

Error: /work/elsewhere/.keploy-run/staging/r1 holds no recording a keploy mock record judged and did not publish (no publish.json)
Error: --lock names the keploy.lock of a staged recording: pass it with --from <dir>