Branches and pull requests
With keploy.lock, your recordings follow git. A replay serves exactly the
recordings that the commit's keploy.lock names. So each git branch carries
its own recordings, a pull request shows which tests it re-records, and merging
the pull request in git merges its recordings. There is no separate merge step
in Keploy.
| In git | What Keploy does |
|---|---|
| A commit | A replay of the commit serves the recordings its keploy.lock pins. |
| A branch | A record on the branch lists its keploy.lock under a Keploy branch of the same name, for the dashboard's Recordings and Branch reviews. |
| A pull request | keploy mock diff --markdown prints the tests the pull request re-records, for a comment on it. |
| A merge | git merges keploy.lock like any other file. |
| A push to the main branch | A green replay of main lists main's keploy.lock as Keploy main, and names the branches it brings into main. |
Every output here is from Keploy 3.9.4 on Linux, with the recordings in Keploy Cloud. The output is trimmed: timestamps, run folders and lines that don't matter are cut.
Before you begin
-
Keploy reads and writes
keploy.lockonly withKEPLOY_PROVEN=1set. The commands below set it on each line. -
Sign in with
keploy login, or setKEPLOY_API_KEY. -
keploy.ymlnames the app (mock.appId), and is committed on main. See keploy.yml and keploy.lock. -
The app's recording pin is on. A person turns it on once for the app (a CI key can't):
KEPLOY_PROVEN=1 keploy mock pin onThe 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.
Warning: keploy.lock does not exist, so every replay of this app here fails until one is committed: make it with KEPLOY_PROVEN=1 keploy mock record --lock keploy.lock, then commit it.Without the pin, a record doesn't list its lock under the branch. It prints the command that turns the pin on instead.
The example
The Go project of the partial re-record guide: an
orders package that reads an order from PostgreSQL and a rate from a rates
API on localhost:8090, with two tests, TestTotalInUSD and TestTotalInEUR.
Each test starts with defer keploytest.T(t)(), from
github.com/keploy/go-sdk/v3/keploytest. keploy.yml holds
mock.command: go test -p 1 -count=1 -json ./... and the app's id.
The repository is on a git host, and origin is its remote.
1. Record on a branch
Record on a branch, never on main. Main gets its recordings when a branch merges into it.
-
Create the branch:
git switch -c add-lock -
Start PostgreSQL and the rates API, and record. The first record of a project makes its
keploy.lockwith--lock:KEPLOY_PROVEN=1 keploy mock record --lock keploy.lockThe record checks each test with the dependencies off, uploads the recordings, writes
keploy.lock, and lists it under the branch:keploy: judging round F (go test -p 1 -count=1 -json ./...): 2 passed, 0 failed, 0 skipped by the test, 0 skipped by keploy
keploy: judging round C (go test -p 1 -count=1 -json ./...): 2 passed, 0 failed, 0 skipped by the test, 0 skipped by keploy
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: 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: committed keploy/orders and its skip lines (pinned in keploy.lock): 2 replayable, 0 quarantinedThe link opens the branch's recordings in Keploy Cloud.
-
Commit
keploy.lockand push the branch:git add keploy.lock
git commit -m "Pin the tests' recordings in keploy.lock"
git push -u origin add-lock
A record on main records and writes keploy.lock too, but it lists nothing.
It says why:
keploy: keploy.lock is not listed in Keploy Cloud: main is the repository's default branch; keploy lists the lock of a branch that merges into it, never its own
2. Open the pull request
Open a pull request for the branch as usual. Its diff shows keploy.lock, so
reviewers see which tests now replay on new recordings.
keploy mock diff says the same thing per test. It compares the branch's
keploy.lock with the one at its merge base with origin/main. --markdown
prints a table for a comment on the pull request:
KEPLOY_PROVEN=1 keploy mock diff --markdown
**e2e tests** keploy.lock vs 6588fe9b5567, the merge base with origin/main — 0 changed, 2 added, 0 removed
| set | test | status | cases | mocks |
|---|---|---|---|---|
| . | .::TestTotalInEUR | added | +0 -0 ~0 | +3 -0 ~0 |
| . | .::TestTotalInUSD | added | +0 -0 ~0 | +3 -0 ~0 |
The GitHub Actions workflow in Run the replay in CI posts this table on every pull request and updates it on each push.
To review the recordings themselves, open the branch in Keploy Cloud: see Find the branch to review.
3. Merge the pull request
Merge the pull request in git. keploy.lock merges with the rest of the
change, and from then on every replay of main serves the recordings it pins.
git switch main
git merge --no-ff add-lock
git push origin main
4. List main in Keploy Cloud
Keploy Cloud's main shows the keploy.lock of your main branch once a green
replay of main lists it.
-
In CI, a replay of a push to the default branch lists it on its own: on GitHub Actions, GitLab CI and Woodpecker,
--list-mainisautoby default. The CI key needs only read access. -
Anywhere else, pass
--list-main on. Keploy lists the lock only whenHEADis the tip oforigin's default branch, after a green replay:KEPLOY_PROVEN=1 keploy mock replay --list-main onkeploy: 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
keploy: listed keploy.lock of commit ea106ef6f0e1 as Keploy main in Keploy Cloud (3 recorded, 0 removed, 0 unchanged); now in main, as main's keploy.lock holds or held each one's own recording of every test it changed: add-lock: https://app.keploy.io/recordings?appId=<app id>&view=e2eThe line names the branches that this lock brought into main: here,
add-lock.
KEPLOY_PROVEN=1 keploy mock register --main lists the lock without a replay.
It takes the same checks. CI's read-scoped key, app admins and admins can run
it:
keploy: listed keploy.lock of commit ea106ef6f0e1 as Keploy main in Keploy Cloud (0 recorded, 0 removed, 3 unchanged): https://app.keploy.io/recordings?appId=<app id>&view=e2e
When main isn't listed
The listing never changes the replay's verdict. When Keploy can't list the lock, the replay still passes or fails on its tests, and a line says why nothing was listed:
-
HEADisn't the tip oforigin's default branch, for example with a local commit not pushed yet:keploy: did not list keploy.lock as Keploy main in Keploy Cloud: HEAD is commit cf7bb0906f2e, not commit ea106ef6f0e1 at the tip of origin's default branch main, so this keploy.lock is not the one git main holds: list it from a checkout of that tip (git fetch origin main && git checkout --detach FETCH_HEAD), or let a green CI replay of a push to main list it -
originnames no default branch that has a commit:keploy: did not list keploy.lock as Keploy main in Keploy Cloud: origin's HEAD names no default branch with a commit (git ls-remote --symref origin HEAD), so keploy cannot check that HEAD is its tipRun the
git ls-remotecommand it names to see whatoriginreports, and check the repository's default branch on your git host.
Work on several branches at once
Each branch records only the tests it changes. Here two branches start from main at the same commit:
-
add-gbpaddsTestTotalInGBPand records it on its own:git switch -c add-gbp main
KEPLOY_PROVEN=1 keploy mock record -c 'go test -p 1 -count=1 -json -run TestTotalInGBP ./...'keploy: keploy.lock: re-recorded .::.::TestTotalInGBP (1), kept 3, start-up kept; recordings 1 uploaded, 0 already on the server; packs 1 uploaded, 0 already on the server
keploy: commit keploy.lock with your change
keploy: listed keploy.lock in Keploy Cloud under branch add-gbp (4 recorded, 0 removed, 0 unchanged): https://app.keploy.io/recordings?appId=<app id>&view=e2e&branch=add-gbp -
price-order-3changesTestTotalInEURand re-records it on its own:git switch -c price-order-3 main
KEPLOY_PROVEN=1 keploy mock record -c 'go test -p 1 -count=1 -json -run TestTotalInEUR ./...'keploy: keploy.lock: re-recorded .::.::TestTotalInEUR (1), kept 2, start-up kept; recordings 1 uploaded, 0 already on the server; packs 1 uploaded, 0 already on the server
keploy: commit keploy.lock with your change
keploy: listed keploy.lock in Keploy Cloud under branch price-order-3 (3 recorded, 0 removed, 0 unchanged): https://app.keploy.io/recordings?appId=<app id>&view=e2e&branch=price-order-3
Each branch's keploy mock diff --markdown shows only its own test:
**e2e tests** keploy.lock vs ea106ef6f0e1, the merge base with origin/main — 0 changed, 1 added, 0 removed
| set | test | status | cases | mocks |
|---|---|---|---|---|
| . | .::TestTotalInGBP | added | +0 -0 ~0 | +3 -0 ~0 |
**e2e tests** keploy.lock vs ea106ef6f0e1, the merge base with origin/main — 1 changed, 0 added, 0 removed
| set | test | status | cases | mocks |
|---|---|---|---|---|
| . | .::TestTotalInEUR | changed | +0 -0 ~0 | +2 -1 ~0 |
Partial re-record explains recording one test on its own.
Replay a teammate's branch
A teammate who checks out the branch replays the recordings that branch's
keploy.lock pins. They need no flag and no database:
git clone <your repository> orders && cd orders
git switch add-gbp
KEPLOY_PROVEN=1 keploy mock replay
INFO pulled set "orders" pinned by /work/mate/orders/keploy.lock: 3 tests, 0 cases; recordings 4 fetched, 0 cached, 0 skipped by keploy.lock and not fetched; packs 4 fetched, 0 cached
keploy: orders: 3 test(s) ran: 3 passed, 0 failed (0 held by keploy), 0 skipped by the test; 0 quarantined (skipped by keploy)
VERDICT passed
Back on main, the same command replays main's two tests, because main's
keploy.lock doesn't pin TestTotalInGBP yet:
INFO pulled set "orders" pinned by /work/mate/orders/keploy.lock: 2 tests, 0 cases; recordings 0 fetched, 3 cached, 0 skipped by keploy.lock and not fetched; packs 0 fetched, 3 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
Merge both
The two branches changed different tests, so git merges keploy.lock with no
conflict:
$ git merge --no-ff add-gbp
Merge made by the 'ort' strategy.
gbp_test.go | 20 ++++++++++++++++++++
keploy.lock | 3 +++
$ git merge --no-ff price-order-3
Auto-merging keploy.lock
Merge made by the 'ort' strategy.
keploy.lock | 2 +-
orders_test.go | 11 ++++++++---
Main's keploy.lock now pins all three tests, each with its newest recording.
After the push, main's replay lists it and names both branches:
keploy: orders: 3 test(s) ran: 3 passed, 0 failed (0 held by keploy), 0 skipped by the test; 0 quarantined (skipped by keploy)
VERDICT passed
keploy: listed keploy.lock of commit 5e29c2e25a63 as Keploy main in Keploy Cloud (2 recorded, 0 removed, 2 unchanged); now in main, as main's keploy.lock holds or held each one's own recording of every test it changed: add-gbp, price-order-3: https://app.keploy.io/recordings?appId=<app id>&view=e2e
When two branches re-record the same test
Every recording has its own digest, so two branches that both re-record a test
change the same line of keploy.lock. The second merge then conflicts:
$ git merge --no-ff usd-b
Auto-merging keploy.lock
CONFLICT (content): Merge conflict in keploy.lock
Automatic merge failed; fix conflicts and then commit the result.
.::.::TestTotalInUSD:
<<<<<<< HEAD
digest: sha256:874ff63f7818bc324e232c6aaefcdeeb2f88006e71d4da6f7a2df711f8674869 # 2026-11-20T14:00Z linux keploy 3.9.4 at 5e29c2e25a63
=======
digest: sha256:782b9c7be3c25037ab493e97a645116e94ea5b0cbcc99e8ee1f47f2eda86a75b # 2026-11-20T14:00Z linux keploy 3.9.4 at 5e29c2e25a63
>>>>>>> usd-b
Keploy won't replay or record from a keploy.lock with conflict markers in
it. Both commands stop and say what to do:
Error: /work/orders/keploy.lock cannot be read: it holds git conflict markers: resolve the conflict first. Keep both sides' entries of different tests; for a test both sides re-recorded, keep one, or record it again
To resolve it:
-
In
keploy.lock, keep one of the twodigest:lines, and delete the other line and the three marker lines. Keep both sides' entries of different tests. -
Commit the merge:
git add keploy.lock
git commit --no-edit -
Replay to check it:
KEPLOY_PROVEN=1 keploy mock replaykeploy: orders: 3 test(s) ran: 3 passed, 0 failed (0 held by keploy), 0 skipped by the test; 0 quarantined (skipped by keploy)
VERDICT passed
To record the test again instead, resolve the conflict first, because the
record refuses the markers too. Then re-record the test with its dependencies
up, as in Partial re-record, and commit
keploy.lock.
Never edit a digest by hand: a replay refuses one it can't verify.
Related
- keploy.yml and keploy.lock: what the lock pins,
the recording pin, and replaying a Keploy branch with
--branch. - Partial re-record: record one test on its own, and see what a branch re-records.
- Keploy Cloud walkthrough: a branch's recordings, and its review.
- Run the replay in CI: the GitHub Actions workflow that replays every pull request and comments its diff.