Skip to main content
View as Markdown

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.

Using VS Code?

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​

  1. Install Keploy, if you haven't.

  2. In your repository's root, install the skill for your agent:

    keploy skill install mock --agent claude-code --project

    Output:

    ✓ installed "mock" skill for claude-code → /home/you/shop/.claude/skills/keploy-mocking/SKILL.md

    For another agent, change --agent. To install for several agents at once, list them with commas: --agent cursor,codex,github-copilot. --all installs for every supported agent.

  3. 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:

AgentFile 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​

  1. Start the dependencies your tests talk to, such as your database (docker compose up -d). The agent records against them.

  2. 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.
===================
  1. Your agent asks you the block's question (ask). Answer it.
  2. On yes, the agent does what do says and runs the block's run command, when it has one. Then it runs keploy mock status again for the next block. It loops until the phase is verified_green, or ci_wired once CI replays the recordings.

Read a NEXT block​

FieldWhat it holds
phaseWhere the setup stands. See the phases below.
summaryOne line on the state, such as how many recordings pass offline.
caveatsThings to know before you call it done, such as no Keploy app yet.
askThe question the agent relays to you, word for word, before it goes on.
runThe command the agent runs when you say yes.
doWhat the agent must do around that command, such as stop the dependencies.
optionsThe other sensible next steps.
protocolThe rules the agent follows for every block.

The phases, in order:

phaseMeaning
uninitializedNo recording yet.
recordedA recording exists, but no replay has shown it passes with the dependencies off.
verified_redThe 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_greenEvery recording passes with the dependencies off.
ci_wiredCI 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 what keploy mock status suggests for a repository with no recording yet.
  • In Keploy Cloud (no --local): the recording goes to your Keploy account, and keploy/.gitignore keeps mocks.yaml out of git. CI replays without --local and needs a KEPLOY_API_KEY secret.

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:

  1. The agent runs keploy login --no-wait --json. Its block names a page and a short code.
  2. 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.
  3. The agent runs keploy login --finish --json to 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 passthrough to 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.