Use the Universal Mocker with a coding agent
Keploy's mocking skill teaches your coding agent how to set up and keep up Keploy mocking for your tests. With it, you can ask your agent to "set up Keploy mocking for this project's tests", and it records and replays your tests' dependency calls step by step.
The agent drives the Keploy CLI. Each keploy mock command prints a
NEXT block: where things stand, a question for you, and the command to run
next. The skill tells the agent to follow those blocks, so you don't have to
remember the commands. The skill doesn't use Keploy's MCP server: everything it
needs comes from the CLI.
The skill works with Claude Code, Cursor, Codex, GitHub Copilot and Antigravity.
The Keploy VS Code extension installs the skill and hands the setup to your agent for you. Read on to do the same from a terminal, or to see what the agent does.
Every output here is from Keploy 3.9.4 on Linux, in a Go repository at
/home/you/shop. The output is trimmed: timestamps and long lines are cut
(…).
Step 1: Install the skill into your repository
-
Install Keploy, if you haven't.
-
In your repository's root, install the skill for your agent:
keploy skill install mock --agent claude-code --projectOutput:
✓ installed "mock" skill for claude-code → /home/you/shop/.claude/skills/keploy-mocking/SKILL.mdFor another agent, change
--agent. To install for several agents at once, list them with commas:--agent cursor,codex,github-copilot.--allinstalls for every supported agent. -
Commit the skill file, so everyone who clones the repository gets it.
Each agent reads the skill from its own place:
Agent (--agent) | File in your repository |
|---|---|
Claude Code (claude-code) | .claude/skills/keploy-mocking/SKILL.md |
Cursor (cursor) | .cursor/rules/keploy-mocking.mdc |
Codex (codex) | .agents/skills/keploy-mocking/SKILL.md |
Antigravity (antigravity) | .agents/skills/keploy-mocking/SKILL.md |
GitHub Copilot (github-copilot) | .github/instructions/keploy-mocking.instructions.md |
To see what an install would write without writing anything, add --dry-run:
keploy skill install mock --agent claude-code --project --dry-run
[dry-run] would install "mock" skill for claude-code → /home/you/shop/.claude/skills/keploy-mocking/SKILL.md (new file)
keploy skill list lists the skills and agents. The mock skill is the one
for the Universal Mocker.
Install it for every repository instead
Without --project, the skill goes to your home directory, and your agent
reads it in every repository:
| Agent | File in your home directory |
|---|---|
| Claude Code | ~/.claude/skills/keploy-mocking/SKILL.md |
| Cursor | ~/.cursor/skills/keploy-mocking/SKILL.md |
| Codex | ~/.agents/skills/keploy-mocking/SKILL.md |
| Antigravity | ~/.gemini/config/skills/keploy-mocking/SKILL.md |
| GitHub Copilot | ~/.copilot/skills/keploy-mocking/SKILL.md |
The home directory's copy starts with a check: the skill applies only in a
repository that uses Keploy (one with a keploy.yml, a keploy/ folder or a
project copy of a Keploy skill), or when you ask for Keploy by name. Elsewhere
the agent ignores it.
Keep the skill up to date
After you update Keploy, run the same install command again. It replaces the skill file with the one your Keploy version ships, so don't edit the file by hand: an install overwrites your edits.
Step 2: Ask your agent to set it up
-
Start the dependencies your tests talk to, such as your database (
docker compose up -d). The agent records against them. -
Ask your agent, for example:
Set up Keploy dependency mocking for this project's tests.
The skill tells the agent to start with keploy mock status, run from the
repository's root. In a repository with no recording yet, it prints:
=== KEPLOY NEXT ===
phase: uninitialized
summary: Keploy is not recording this repo's dependency calls yet.
caveats:
- keploy.yml has no mock.appId, so no recording is in the Keploy cloud. To publish one, record on a branch other than main with `keploy mock record --app <name>`, or run `keploy app create` first.
ask: Want me to set up Keploy mocking? I'll record the real calls your tests make to databases and APIs once, then prove the whole suite passes with every one of them switched off.
do: Find the command that runs this project's test suite first (package.json scripts.test, `go test ./...`, `pytest`, `mvn test`), and use it exactly in the commands below. Set it up end to end: … (3) record: keploy mock record --local -c '<your test command>' … (4) stop the dependencies and prove it: keploy mock replay --local -c '<your test command>' --on-miss fail; … (6) run `keploy mock status` and follow the NEXT block to wire CI. Commit keploy.yml and keploy/ (keep keploy/.gitignore as the CLI wrote it).
options:
- record the test suite's dependency calls
- stop
protocol: This output uses a NEXT block. Relay `ask` to the dev verbatim and wait; run `run` on yes; loop until phase=verified_green (or ci_wired once CI replays every recording). Never edit a recording to make a failing test pass.
===================
- Your agent asks you the block's question (
ask). Answer it. - On yes, the agent does what
dosays and runs the block'sruncommand, when it has one. Then it runskeploy mock statusagain for the next block. It loops until the phase isverified_green, orci_wiredonce CI replays the recordings.
Read a NEXT block
| Field | What it holds |
|---|---|
phase | Where the setup stands. See the phases below. |
summary | One line on the state, such as how many recordings pass offline. |
caveats | Things to know before you call it done, such as no Keploy app yet. |
ask | The question the agent relays to you, word for word, before it goes on. |
run | The command the agent runs when you say yes. |
do | What the agent must do around that command, such as stop the dependencies. |
options | The other sensible next steps. |
protocol | The rules the agent follows for every block. |
The phases, in order:
phase | Meaning |
|---|---|
uninitialized | No recording yet. |
recorded | A recording exists, but no replay has shown it passes with the dependencies off. |
verified_red | The last replay failed. The summary says why: the tests failed, the replay couldn't run, the replay wrote no coverage report for the coverage floor you set, or coverage is under that floor. |
verified_green | Every recording passes with the dependencies off. |
ci_wired | CI replays every recording. |
Only a verified_red whose tests failed points at your code. The other three
reasons are about the run.
keploy mock status --json prints the same block as one JSON object, plus the
state of every recording:
{
"flow": "mock",
"phase": "uninitialized",
"summary": "Keploy is not recording this repo's dependency calls yet.",
"ask": "Want me to set up Keploy mocking? …",
"agent_todo": "Find the command that runs this project's test suite first …",
"caveats": ["keploy.yml has no mock.appId, so no recording is in the Keploy cloud. …"],
"options": [{ "label": "record the test suite's dependency calls" }, { "label": "stop" }],
"mock": {
"sets": [],
"cloud": { "state": "no_app", "tests": 0, "sets": 0 }
},
…
}
Choose where the recording lives
The first time, your agent asks you where to keep the recording:
- In the repository (
--local): the recording is committed with your code. You need no Keploy account, and CI needs no secret. This is whatkeploy mock statussuggests for a repository with no recording yet. - In Keploy Cloud (no
--local): the recording goes to your Keploy account, andkeploy/.gitignorekeepsmocks.yamlout of git. CI replays without--localand needs aKEPLOY_API_KEYsecret.
After that, the agent keeps each recording where it is: the run commands
in each block already carry the right flag.
Sign in from your agent's shell
If a Keploy command needs your account, it exits with code 5 and the reason
auth_required. A plain keploy login waits for you at a terminal, which an
agent's shell doesn't have, so the skill tells the agent to sign in in two
parts:
- The agent runs
keploy login --no-wait --json. Its block names a page and a short code. - The agent shows you the page and the code. You open the page in your own browser, check the code, and approve. The agent never opens the page, types the code or asks for a password.
- The agent runs
keploy login --finish --jsonto collect the session.
keploy login lists both flags and the exit
codes. In CI nobody can approve a sign-in: the job uses a KEPLOY_API_KEY
secret.
Check each test on its own
With KEPLOY_PROVEN=1 in the environment your agent's commands run with,
every block names KEPLOY_PROVEN=1 in its commands, and the agent records and
checks each test on its own. The first block then reads:
=== KEPLOY NEXT ===
phase: uninitialized
summary: Keploy is not recording this repo's dependency calls yet.
caveats:
- keploy.yml has no mock.appId, so no recording is in the Keploy cloud. To publish one, record on a branch other than main with `KEPLOY_PROVEN=1 keploy mock record --app <name>`, or run `keploy app create` first.
…
The VS Code extension's setup task tells your agent to run every keploy
command this way. See
Prove each test offline for what the per-test
checks need.
What the skill tells your agent not to do
- Edit a recording (
mocks.yaml) by hand to make a red replay green. - Switch to
--on-miss passthroughto make a red replay green. That lets calls reach the real services, so the replay no longer proves anything. - Rewrite an expected value in a test to make a red test pass.
- Write a hand-made stub for a new test that talks to a dependency. It records the test instead.
When a replay fails with no recorded mock matched an outgoing call, your code
now makes a call the recording doesn't have. If you changed the code on
purpose, the agent re-records against the real dependencies, or adds just the
new calls with --on-miss record while they are up. If not, that call is the
regression, and the agent tells you.
Related
- VS Code walkthrough: the extension installs the skill and hands the setup to your agent.
- Mock your tests: the commands the agent runs, in full.
- Troubleshooting: what each failure means and how to fix it.
- Reference: every
keploy mockcommand and flag.