# Walkthrough: set up the Universal Mocker in VS Code

> A step-by-step tour of the Keploy VS Code extension, from installing it to a green replay of your tests with their dependencies switched off, a red test, the staged files and the CI workflow.

# Walkthrough: set up the Universal Mocker in VS Code

This walkthrough takes one project through the Keploy VS Code extension, from
installing it to a green replay of your tests with their dependencies switched
off. You also see a red test, stage the files to commit, and add the CI
workflow.

Each step names what you select and what the extension shows. The steps are
from version 3.1.1 of the extension, with Keploy 3.9.4, the CLI it
downloads. For every setting and command, see the
[VS Code extension page](/docs/running-keploy/utg-vscode-extension/).

:::note Two screenshots are on their way

The screenshots are from a real run of the extension on Linux. Two boxes
marked **Screenshot coming** stand where two more go: the browser's sign-in
page and your agent's chat. Each box says what the screen shows.

:::

## Before you begin

You need:

- VS Code 1.125 or later, on Linux (x86-64 or arm64) or on a Mac with Apple
  silicon. The [requirements](/docs/running-keploy/utg-vscode-extension/#requirements)
  list the Linux versions that work. Windows support in the extension is
  coming.
- Claude Code or GitHub Copilot in VS Code, or Cursor's agent in Cursor.
- A project in a Git repository, with tests that call a database or an API.
  To follow along with a sample, create the package from
  [Step 1 of the Go quickstart](../quickstarts/go.md#step-1-create-the-sample-package),
  commit it, and start its dependencies as its Step 2 shows.
- A free Keploy account. You sign in from the extension in Step 3.

## Step 1: Install the extension

1. In VS Code, open the **Extensions** view.
2. Search for **Keploy**.
3. Select **Install** on **Keploy: API Testing, Mocks & Service
   Virtualization**. Its ID is `keploy.keployio`.
4. Select the **Keploy** icon in the Activity Bar.

The **Set up** checklist opens. It lists each step of this walkthrough, and a
step that isn't done runs the command that does it when you select it.

The extension also adds a guided tour to VS Code. To open it, run **Welcome:
Open Walkthrough** from the Command Palette and choose **Get started with
Keploy**.

## Step 2: Let the extension download the Keploy CLI

The download starts by itself when the extension is installed. You don't have
to do anything.

- A notification, **Keploy: downloading the CLI (_version_)**, shows how much
  has arrived, such as _125.6 MB of 125.6 MB_ when it ends. To stop it, select **Cancel**.
- The status bar shows **Keploy: CLI** and the percentage.
- The CLI goes into `~/.keploy/bin`, and the extension checks it against
  Keploy's published checksum before it installs it. No step needs `sudo`.

When the download ends, the checklist ticks **Keploy CLI installed**.

If you cancelled, run **Keploy: Install or update the CLI** to start the
download again.

## Step 3: Sign in

1. In the checklist, select **Signed in to Keploy**. Or run **Keploy: Sign
   in** from the Command Palette.

2. VS Code asks **Do you want Code to open the external website?** for
   `https://app.keploy.io/activate`. Select **Open**.

   

   Your browser opens Keploy's sign-in page. In VS Code, a **Keploy sign-in**
   notification shows the page's address and a code:

   ```text
   Keploy sign-in: Open https://app.keploy.io/activate, enter the code XXXX-XXXX, and approve it. Tell me when it says you are signed in.
   ```

   The CLI writes this text for coding agents too, which is why it ends with
   "Tell me". In VS Code you don't need to do anything else: the notification
   waits for your approval.

   

3. In your browser, sign in, type the code the notification shows, and
   approve the sign-in. The page never fills the code in for you: typing it
   ties the approval to the sign-in VS Code started. Approve only a sign-in
   you started yourself.

   VS Code says **Keploy: you are signed in.** The checklist ticks **Signed in
   to Keploy**.

   If you don't approve in time, VS Code says **Keploy: the sign-in was not
   approved in your browser in time.** Select **Try again** for a new code.

:::note Screenshot coming

The browser's page with the code typed in. The account's email is blurred.

:::

The CLI stores the session, not the extension. Every `keploy` command reads
it, in VS Code's runs, in your terminal and in your agent's terminal.

## Step 4: Hand the setup to your coding agent

1. In the checklist, select **Project set up by your agent**.

   If VS Code asks whether you trust the folder, trust it: Keploy runs your
   project's own test command, so it needs a trusted workspace.

2. The extension installs Keploy's skill for this project, then opens your
   agent's chat with the setup task typed in. Claude Code is used when you
   have it, otherwise GitHub Copilot:

   | Agent          | Where the skill goes                                  | Where the task goes                          |
   | -------------- | ----------------------------------------------------- | -------------------------------------------- |
   | Claude Code    | `.claude/skills`                                      | a new Claude Code conversation               |
   | GitHub Copilot | `.github/instructions/keploy-mocking.instructions.md` | the chat, in agent mode                      |
   | Cursor's agent | `.cursor/rules`                                       | your clipboard: paste it into the agent chat |

   The task starts like this, with Claude Code:

   ```text
   Set up Keploy dependency mocking for this project's tests, following the keploy mock skill (.claude/skills).
   ```

   If the agent's chat doesn't open, VS Code says **Keploy: _agent_ did not
   open. The setup task is on your clipboard.** Paste it into the agent's
   chat.

3. Send the task. Then let your agent work. It follows each step the CLI prints, starting with
   `KEPLOY_PROVEN=1 keploy mock status --json`:

   - it sets `mock.command` in `keploy.yml` to your test command;
   - it adds the test-side hook the skill names for your framework, such as
     `keploytest` for Go;
   - it records your tests, with your dependencies running:
     `KEPLOY_PROVEN=1 keploy mock record --lock keploy.lock`;
   - it replays them until the replay is green:
     `KEPLOY_PROVEN=1 keploy mock replay --lock keploy.lock`.

   On `main` or `master`, the agent first switches to a work branch named
   `keploy/<your folder's name>`. It asks you before any step that changes
   more than `keploy.yml`, `keploy.lock` and your test files.

:::note Screenshot coming

The agent's chat with the setup task, and the checklist beside it with
**Project set up by your agent** ticked.

:::

To choose the agent yourself, run **Keploy: Hand the setup to another agent**.

## Step 5: Record from VS Code

Your agent has recorded once. You can record again yourself, for example after
you add a test. Your dependencies must be running.

1. Run **Keploy: Record** from the Command Palette.
2. If you're on `main` or `master`, the extension says:

   ```text
   Keploy records on a work branch, not on main: the default branch's recordings change only through merges, so CI replays what was reviewed.
   ```

   Select **Create keploy/_name_ and record** to create the branch, switch to
   it and record there. Nothing runs if you close the message.

   

3. The record runs `keploy mock record --lock keploy.lock` in a VS Code
   terminal, with `KEPLOY_PROVEN=1`. When it ends, the checklist says
   **Recorded: _n_ tests in Keploy Cloud**, and the terminal ends like this:

   ```text
   keploy: recorded from uncommitted changes in 2 file(s); the recording matches the code only once you commit them with keploy.lock
   keploy: commit keploy.lock with your change
   keploy: keploy.lock is not listed in Keploy Cloud: the pin of app <app id> is off, so its replays read Keploy branches, which a listed one could change; `KEPLOY_PROVEN=1 keploy mock pin on` turns it on, then `KEPLOY_PROVEN=1 keploy mock register` lists the lock
   keploy: committed keploy/docs-vscode-orders and its skip lines (pinned in keploy.lock): 2 replayable, 0 quarantined
   ```

   The first two lines ask you to commit `keploy.lock` with your changes,
   which Step 8 does. The third line shows while the app's recording pin is
   off: [Turn on the app's recording pin](../guides/keploy-yml-and-lock.md#turn-on-the-apps-recording-pin)
   explains it.

   

The record uploads the recording to Keploy Cloud and pins it in
`keploy.lock`. The [keploy.yml and keploy.lock guide](../guides/keploy-yml-and-lock.md)
explains the lock.

## Step 6: Replay with the dependencies off

1. Stop your dependencies, such as the database and the API your tests call.
2. Run **Keploy: Replay** from the Command Palette, or select **Replay
   green** in the checklist while it isn't ticked.

   The replay runs `keploy mock replay` in a terminal, with `KEPLOY_PROVEN=1`.
   It reads `keploy.lock` and answers every call your tests make from the
   recording.

3. When the replay exits 0 and no test failed, its terminal ends with
   `VERDICT  passed`, and the checklist ticks **Replay green**. Only a replay
   you start in VS Code ticks it, from **Keploy: Replay** or the **Testing**
   view: a replay in your agent's terminal doesn't.

   

You can also replay from VS Code's **Testing** view. A project whose
recordings are in Keploy Cloud shows one row there, **Keploy Cloud: _n_
tests**, which replays as **Keploy: Replay** does. Run **Test: Run All Tests**
from the Command Palette, or select the row's run button, and the row turns
green or red. The view shows only the runs you start in it, not a **Keploy:
Replay** from the Command Palette. Recordings kept on your machine with
`--local` show one row per recording set instead, with its tests under it.

## Step 7: See a red test

1. Change one test so it fails, for example by changing the value it expects.
   In the Go sample, change both `50`s in `TestTotalInUSD` to `51`.
2. Run **Keploy: Replay** again.

The replay fails, and VS Code shows it in these places:

- **The replay's terminal** ends with the result. `FAILED` names the test
  that failed, and `VERDICT` gives the exit code of your test command:

  ```text
  keploy: docs-vscode-orders: 2 test(s) ran: 1 passed, 1 failed (0 held by keploy), 0 skipped by the test; 0 quarantined (skipped by keploy)
  FAILED  .::TestTotalInUSD: the test failed
  MOCKED  .::TestTotalInUSD: [::1]:5432 (mocked: if this is your app, start it from the runner, then re-record)
  MOCKED  .::TestTotalInUSD: [::1]:8090 (mocked: if this is your app, start it from the runner, then re-record)
  MOCKED  .::TestTotalInEUR: [::1]:5432 (mocked: if this is your app, start it from the runner, then re-record)
  VERDICT  failed: the test command exited 1
  ```

  Your test's own failure message is above these lines, in your test
  command's output.

  

- **The Testing view**, for a replay you run from it: the **Keploy Cloud**
  row turns red.
- **The Test Results view**, for the same run: select the red row to see its
  message. It ends with the `FAILED` and `VERDICT` lines:

  ```text
  keploy mock replay exited 1, and its report says a test failed: see its terminal.
  FAILED  .::TestTotalInUSD: the test failed
  VERDICT  failed: the test command exited 1
  ```

  

The extension shows no diff view of its own. The difference is in your test's
failure message, as when you run the tests without Keploy.

A test can also fail because it makes a call the recording doesn't have. Then
the terminal names that call and says what to do, as
[Step 5 of the Go quickstart](../quickstarts/go.md#step-5-add-a-test-and-see-a-call-with-no-recording)
shows.

Change the test back, and replay again to see it green.

## Step 8: Stage the files to commit

1. In the checklist, select **keploy.yml, keploy.lock and the test edits
   staged**.
2. In the list that opens, check the files. `keploy.yml`, `keploy.lock` and
   the files that changed after your agent started are picked. Keploy's skill
   for the project is listed unpicked: pick it to share the setup with your
   team.
3. Select **OK**.

Source Control opens with the files staged. When its message box is empty,
the extension puts `test: record dependency mocks with Keploy` in it. Review
the changes, then commit. The extension never commits for you, and never changes `.gitignore`.

## Step 9: Replay in CI

For a Go or Node project in a GitHub repository:

1. In the checklist, select **CI replays keploy.lock (GitHub Actions)**.

   The extension writes `.github/workflows/keploy.yml`. It never writes over a
   file that is already there. On every pull request and every push to main,
   the workflow runs `keploy mock replay --lock keploy.lock --on-miss fail`
   with `KEPLOY_PROVEN=1`.

2. The workflow needs one repository secret, `KEPLOY_API_KEY`: a read-only CI
   key. Ask your Keploy admin for one. The notification's **Open the CI key
   page** button opens the page where the admin makes it.
3. Store the key as the repository's secret. Run this in a terminal, and paste
   the key when it asks:

   ```bash
   gh secret set KEPLOY_API_KEY
   ```

   The notification's **Copy the secret command** button copies this command.
   Selecting either button closes the notification.

4. Commit the workflow with `keploy.yml` and `keploy.lock`, and push.

For any other project or CI, the extension writes no workflow and says so. The
[Other CI systems](../guides/ci.md#other-ci-systems) section shows the replay step to add
yourself.

## Step 10: Invite your team

Select **Teammates invited** in the checklist. The Keploy app's **Add User**
page opens, where an admin adds your teammates.

A teammate who clones the repository signs in and replays. The replay reads the
committed `keploy.yml` and `keploy.lock`, and downloads the recordings the lock
pins.

## Next steps

- [The VS Code extension](/docs/running-keploy/utg-vscode-extension/): every
  command, setting and platform note, and troubleshooting.
- [VS Code quickstart](../quickstarts/vscode.md): record and replay a sample
  from the extension without a coding agent, with the real output of each
  step.
- [Go quickstart](../quickstarts/go.md): the same record and replay in a
  terminal, with the real output of each step.
- [Partial re-record](../guides/partial-re-record.md): re-record one changed
  test without running the whole suite again.
- [Troubleshooting](../troubleshooting.md): what a failing record or replay
  prints, and how to fix it.
