Troubleshoot the Universal Mocker
This page lists what Keploy prints when a record or a replay goes wrong, what causes it, and how to fix it.
Every output here is from Keploy 3.9.4, in a Go project whose tests call a
rates API on localhost:8090, with the recordings kept in the repository
(--local). The output is trimmed: timestamps and lines that don't matter are
cut. Tags such as #a0064248d208 change on every run, so this page shows them
as #….
Start with keploy mock status
Run keploy mock status after any record or replay. It reads the files under
keploy/ and prints a block that says where the project is and what to run
next:
$ keploy mock status
=== KEPLOY NEXT ===
phase: verified_red
summary: The last replay of default failed: the tests failed on the last replay (exit 1).
ask: Want me to find out why? A red replay is either a regression in the code, or a dependency call the recording does not have.
run: keploy mock replay --local -c 'go test -count=1 ./...' --on-miss fail
do: Re-run the replay and read its output. `no recorded mock matched an outgoing call` lines are calls the recording lacks: …
options:
- re-run the replay → keploy mock replay --local -c 'go test -count=1 ./...' --on-miss fail
- re-record against the real dependencies → keploy mock record --local -c 'go test -count=1 ./...'
===================
| Field | What it says |
|---|---|
phase | Where the project is. The table below lists each phase. |
summary | The state of each recording, in one sentence. |
caveats | Anything else to know, such as recordings not in Keploy Cloud yet. |
ask | The question a coding agent asks you before it runs run. |
run | The command to run next. |
do | The steps behind run, in full. |
options | The other commands that make sense now. |
protocol | How a coding agent should use the block. |
| Phase | What it means | What to do |
|---|---|---|
uninitialized | Nothing is recorded yet. | Record with the real dependencies up. |
recorded | A recording exists, but no replay has shown that the tests pass with every dependency off since it was made. | Stop the dependencies and replay with --on-miss fail. |
verified_red | The last replay failed. | Read its output. The sections below cover each failure. |
verified_green | The last replay passed, and the recording answered every call. | Run the replay in CI. |
A recorded summary says why the recording isn't proven yet:
| Summary ends with | Cause |
|---|---|
(never replayed on this machine) | You recorded but haven't replayed on this machine. A fresh clone starts here too. |
(re-recorded since its last replay) | You recorded again after the last replay. |
(--on-miss passthrough lets a call the recording does not have reach the real dependency) | The last replay let unrecorded calls through to the real services, so it proves nothing. |
A call has no recording
Your test fails in a replay, and Keploy prints no recorded mock matched an outgoing call. Here a test was added after the last record, and its call to
/rates?from=EUR&to=GBP isn't in the recording:
$ keploy mock replay --local -c "go test -count=1 ./..."
🐰 Keploy(agent): WARN mock mismatch: no matching mock for outgoing call {"protocol": "HTTP", "destination": "{}:8090 #…", "call": "GET /{}", "path_tag": "#…", "match_phase": "no_schema_candidates", "candidates": 1, "closest": "mock-0", "next_step": "Only values drifted (query.to). …"}
--- FAIL: TestEURGBP (0.00s)
rate_test.go:41: GET /rates?from=EUR&to=GBP: 502 Bad Gateway
FAIL
FAIL example.com/rates 0.149s
🐰 Keploy: INFO mock replay summary {"loaded": 1, "consumed": 1, "missed": 1}
🐰 Keploy: WARN no recorded mock matched an outgoing call {"protocol": "HTTP", "call": "GET /{}", "path_tag": "#…", "destination": "{}:8090", …}
Mock mismatch: [HTTP] GET /rates [path tag #…] → localhost:8090 [host tag #…]
Hint: Only values drifted (query.to). If the change is expected, re-record the mock set with 'keploy mock record', or, with the dependency reachable, capture the new calls with 'keploy mock replay --on-miss record'. …
🐰 Keploy: INFO test command exited non-zero; mirroring its exit code {"phase": "replay", "exitCode": 1}
A replay runs with --on-miss fail unless you say otherwise. Keploy answers a
call that the recording doesn't have with an error, and never lets it reach the
real service. An HTTP client gets 502 Bad Gateway. The log lines write {}
and a tag where the host and the path go. The Mock mismatch line at the end
names them, and its Hint says what is different:
| Hint says | Cause |
|---|---|
Only values drifted (query.to). | The call matches a recorded call except for the values in the brackets. Here the test asked for to=GBP, and the recording has only to=USD. |
No recorded mocks were available to match against for this protocol in the selected mock set. | The recording has no call of this kind at all. If the replay also warns the mock set is empty, there is no recording: see The mock set is empty. |
Each test is served the HTTP calls it recorded. | Keploy serves each test only the HTTP calls that it recorded itself. If another test recorded this call, and every test may make it, such as fetching a token, declare it as a session call. The hint calls the file keploy.yaml: it is your project's keploy.yml. |
If you didn't mean to change the call, the replay found a regression: fix the code. If you did, record the new call:
-
Start the real dependencies.
-
Record again:
keploy mock record --local -c "go test -count=1 ./..."ok example.com/rates 0.008s
🐰 Keploy: INFO recorded mocks {"mocks": 2, "mock-set": "default"}
🐰 Keploy: INFO test command finished successfully {"phase": "record"} -
Stop the dependencies, and replay:
keploy mock replay --local -c "go test -count=1 ./..."ok example.com/rates 0.149s