Skip to main content
View as Markdown

Universal Mocker features​

This page lists what Universal Mocker does in Keploy 3.9.4. Each row links to the page that shows it.

Record and replay any test command​

FeatureWhat it does
Any test commandKeploy wraps the command that runs your tests: go test, pytest, npx jest, mvn test, npx playwright test, or a shell script. You write no mock code and change no test.
Record oncekeploy mock record runs your tests against the real dependencies and saves each outgoing call with its answer.
Replay with the dependencies offkeploy mock replay runs the same command and answers each call from the recording. Your test framework still decides which tests pass.
A call with no recording gets an errorA call Keploy can't match to any recording gets an error instead of a real answer (--on-miss fail, the default), and the replay names it. By default, the run fails when a test fails on that error, and --strict fails it even when no test does: see A test that doesn't fail on the answer. The note below the table says what else a replay lets through.
Add the calls of a new testWith --on-miss record, a call the recording doesn't have goes to the real dependency, and Keploy adds it to the recording.
Catch a dependency that changed--strict fails the run when a call missed its recorded mock, even when the tests passed.
Run with no Keploy account--local keeps the recordings in your repository, so you record and replay without signing in.
Services that Docker Compose startsRecord the calls your tests make to the services in a compose file, then replay them with the compose stack down.

In a replay of the whole run, Keploy 3.9.4 can answer a call with a new id from a similar recorded call and count it as answered: see Times, dates and ids that change. A DNS lookup the recording doesn't have doesn't fail a replay, and other UDP (not DNS) isn't intercepted: see Network isolation in replay.

Check each test on its own​

These run with KEPLOY_PROVEN=1 set.

FeatureWhat it does
Prove each test offlinekeploy mock record replays every test with the dependencies off before it keeps the recording. A test that doesn't replay is skipped, with Keploy's reason and what to do about it.
Replay each test on its own recordingkeploy mock replay runs the kept tests, each against its own recording. A green replay means every test it ran passed with no real dependency behind it.
Mark where each test starts and endsGo tests use github.com/keploy/go-sdk/v3, Playwright tests use @keploy/playwright, and any other framework makes two HTTP calls per test.
Find out why a test is skippedkeploy mock explain says why a test is skipped or run. keploy mock quarantine skips a test in CI with your reason. keploy mock replay --all also runs the skipped tests.
Judge the recordings againkeploy mock judge judges the recordings again, for example after a Keploy upgrade, and drops the skips of tests that now replay.
Check a hand edit offlinekeploy mock check reads the recordings offline and names each mistake with its file, line and fix.

Share recordings through Keploy Cloud​

Keploy reads and writes keploy.lock only with KEPLOY_PROVEN=1 set, and Keploy Cloud needs a sign-in.

FeatureWhat it does
Commit two filesThe recordings live in Keploy Cloud. Your repository holds only keploy.yml and keploy.lock.
Pin each test to its recordingkeploy.lock names one recording for each test and one for the start-up, by the sha256 digest of its bytes, so a recording can't change under the lock.
Keploy branches follow git branchesA record on a git branch lists its keploy.lock under a Keploy branch named after it. Keploy never lists a record on main.
Merge with the pull requestgit merges keploy.lock with the rest of the change. A green replay of main lists main's lock as Keploy main, in CI with no extra step.
Resolve a keploy.lock conflictWhen two branches re-record the same test, keep one recording. Keploy refuses a lock with conflict markers and says how to resolve it.
Turn on the recording pinkeploy mock pin on makes every replay of the app read keploy.lock.
Publish a staged recordingWhen a record's own publish fails, Keploy keeps the recording in a staging folder and prints the line that publishes it.
Replay a teammate's recordingsA teammate signs in, clones the repository and replays. The replay downloads the recordings keploy.lock pins.
List a branch's recordings for the dashboardkeploy mock register lists keploy.lock's recordings in Keploy Cloud under the git branch.
Use the mock registrykeploy mock upload uploads mocks to Keploy's mock registry, and keploy mock download downloads them.

Re-record only what changed​

These run with KEPLOY_PROVEN=1 set.

FeatureWhat it does
Record a new test on its ownA record whose -c runs one test records only that test. keploy.lock keeps every other test's recording.
Re-record a test whose calls changedThe same filtered record replaces that test's recording, and only its entry in keploy.lock changes.
Replay a few testsA replay whose -c runs some tests replays only those.
See what a branch re-recordskeploy mock diff compares keploy.lock with the one at your branch's merge base. --markdown prints a table for a pull request comment.

Keep replays off the real network​

FeatureWhat it does
What a replay does with each callKeploy answers each recorded call from the recording. By default, a TCP connection the recording doesn't have gets an error instead of reaching the real service, and the replay names it. DNS lookups and UDP work differently: see the next rows and the note below the table.
DNS lookups answered by KeployKeploy answers a recorded lookup from the recording. By default, it answers any other lookup itself.
Let a call out on purpose--on-miss passthrough, --pass-through-ports and --allow-egress dns each let one kind of call reach the real network.
Tell whether a replay went outThe replay's last line says whether the recording answered every connection the tests opened. It doesn't count lookups sent out with --allow-egress dns, or UDP. Each flag that lets something out prints a real egress opened by line.

UDP that isn't DNS, ICMP and raw sockets aren't intercepted. See What a replay doesn't intercept.

Handle values that change​

FeatureWhat it does
New times and request idsA replay answers a call whose time or request id is new on this run from the recording.
Ids your test sends, then uses againWith KEPLOY_PROVEN=1, Keploy learns at record where an id goes, and the replay expects the new id in each call.
Calls made outside every testCalls your app makes outside every test, such as in Go's TestMain, go to the set's start-up recording. The guide says which test a replay answers each one in.
Serve a call to every testA sessionCalls entry in keploy.yml serves a call your app makes once and keeps, such as fetching a token, to every test.
A clock shifted back to the recordingWith KEPLOY_PROVEN=1, a test that compares a time with the clock replays on a clock shifted back to its recording. A test that fails in the judging rounds is quarantined.

Find out what to run next​

FeatureWhat it does
keploy mock statusPrints where the project is and the command to run next.
Status as JSONkeploy mock status --json prints the same block and the full mock state as one JSON object, for an editor or a coding agent.
Replay resultsEach replay writes what it proved to keploy/<set>/last-replay.yaml.
Replay in CIA GitHub Actions workflow replays every pull request and push to main with no dependency running, signed in with a read-only CI key, and comments the tests a pull request re-records.
Your test command's exit codekeploy mock record and keploy mock replay exit with your test command's own exit code, so a failing test fails your CI job.
Fixes for each errorWhat a failing record or replay prints, what causes it, and how to fix it.

Run it where you work​

FeatureWhat it does
Linux, macOS and DockerRecord and replay on Linux, on macOS on Apple silicon with no sudo, and through a docker run or docker compose command. Native Windows support is coming.
Databases, queues and APIsHTTP, gRPC, PostgreSQL, MySQL, MongoDB, Redis, Kafka and more. The overview lists each one for Linux and macOS.
Notes for each dependencyKeploy tells dependencies apart by their first bytes, on any port, and reads TLS with its own CA. The page also covers PostgreSQL and MySQL logins, Redis blocking pops and SQS polls at replay.
VS CodeThe Keploy VS Code extension installs the Keploy CLI, signs you in, and hands the project setup to your coding agent.
Coding agentskeploy skill install mock gives Claude Code, Cursor, Codex, GitHub Copilot or Antigravity the steps to record and replay your tests, following each NEXT block.
Every command and flagEach keploy mock command and flag, the keploy.yml keys, the environment variables and the exit codes.