From 23cea1c5f2bfa99594dbfbedd7b486b5afc47672 Mon Sep 17 00:00:00 2001 From: slayerjain Date: Thu, 19 Nov 2026 23:54:29 +0530 Subject: [PATCH 1/4] docs: add a Universal Mocker section to the navbar and sidebar Universal Mocker (keploy mock) had no place of its own: its pages sat in the Integration Testing list, and the Products menu named only Integration Testing, API Testing and UI Testing. - The Products menu lists "Universal Mocker (Service Virtualization)". - The sidebar has a Universal Mocker category right after API Testing, opening on a new overview page: how record and replay work, when to pick it over Integration Testing or API Testing, and the platforms and dependencies Keploy 3.9.3 supports, from the parsers it registers on each OS. - The mock quickstart, Mock your tests and Mock Registry pages move into the section, and the VS Code extension page is listed there. Each old URL redirects to its new one, and links across the docs point at the new URLs. Signed-off-by: slayerjain --- docusaurus.config.js | 17 +++ static/img/universal-mocker/record-replay.svg | 42 ++++++ .../keploy-cloud/keploy-console.md | 2 +- .../keploy-cloud/time-freezing.md | 2 +- .../keploy-explained/integrations-vscode.md | 4 +- .../running-keploy/cli-commands.md | 4 +- .../running-keploy/utg-vsc-extension.md | 4 +- .../version-4.0.0/server/installation.md | 4 +- .../mock-quickstart.md | 0 .../mock-registry.md | 0 .../mock-your-tests.md | 0 .../universal-mocker/overview.md | 127 ++++++++++++++++++ .../version-4.0.0-sidebars.json | 34 ++++- 13 files changed, 225 insertions(+), 15 deletions(-) create mode 100644 static/img/universal-mocker/record-replay.svg rename versioned_docs/version-4.0.0/{running-keploy => universal-mocker}/mock-quickstart.md (100%) rename versioned_docs/version-4.0.0/{keploy-cloud => universal-mocker}/mock-registry.md (100%) rename versioned_docs/version-4.0.0/{running-keploy => universal-mocker}/mock-your-tests.md (100%) create mode 100644 versioned_docs/version-4.0.0/universal-mocker/overview.md diff --git a/docusaurus.config.js b/docusaurus.config.js index a41c744d2..8809dd2ce 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -225,6 +225,19 @@ s.parentNode.insertBefore(b, s);})(window.lintrk);`, from: "/ui-capture/install-sdk/", to: "/running-keploy/ui-capture/#install-the-sdk", }, + // Pages that moved into the Universal Mocker section. + { + from: "/running-keploy/mock-quickstart/", + to: "/universal-mocker/mock-quickstart/", + }, + { + from: "/running-keploy/mock-your-tests/", + to: "/universal-mocker/mock-your-tests/", + }, + { + from: "/keploy-cloud/mock-registry/", + to: "/universal-mocker/mock-registry/", + }, ], }, ], @@ -330,6 +343,10 @@ s.parentNode.insertBefore(b, s);})(window.lintrk);`, label: "API Testing (AI)", to: "/running-keploy/api-test-generator", }, + { + label: "Universal Mocker (Service Virtualization)", + to: "/universal-mocker/overview", + }, { label: "UI Testing", to: "/running-keploy/ui-capture", diff --git a/static/img/universal-mocker/record-replay.svg b/static/img/universal-mocker/record-replay.svg new file mode 100644 index 000000000..56770d98c --- /dev/null +++ b/static/img/universal-mocker/record-replay.svg @@ -0,0 +1,42 @@ + + Universal Mocker: record, then replay + Record: your test command calls the real dependencies through Keploy, which saves each call and answer. Replay: the same test command runs, the dependencies are off, and Keploy answers each call from the recording. + + + + + + + + 1. Record (once, dependencies up) + + Your test command + go test, pytest, jest… + + keploy mock record + saves each call + answer + + Real dependencies + databases, queues, APIs + + + + + + Recordings + + + 2. Replay (dependencies off) + + Your test command + unchanged + + keploy mock replay + answers from the recording + + Dependencies + switched off + + + × + diff --git a/versioned_docs/version-4.0.0/keploy-cloud/keploy-console.md b/versioned_docs/version-4.0.0/keploy-cloud/keploy-console.md index f67bcde5f..871c72550 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/keploy-console.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/keploy-console.md @@ -85,7 +85,7 @@ Similarly, if the test case result is the new expected response, we can normalis - [Install Keploy](/docs/server/installation/) — prerequisite before starting the console. - [Keploy Cloud Application Settings Guide](/docs/keploy-cloud/application-settings/) — add an application to the console. -- [Mock Registry](/docs/keploy-cloud/mock-registry/) — manage mocks used during test runs. +- [Mock Registry](/docs/universal-mocker/mock-registry/) — manage mocks used during test runs. - [Time Freezing](/docs/keploy-cloud/time-freezing/) — stabilize time-sensitive test results. ## Need Help? diff --git a/versioned_docs/version-4.0.0/keploy-cloud/time-freezing.md b/versioned_docs/version-4.0.0/keploy-cloud/time-freezing.md index 25c2768bd..0d8b66b35 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/time-freezing.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/time-freezing.md @@ -138,4 +138,4 @@ To build natively instead, download the same `go_freeze_time_` helper, run - [Dynamic Deduplication](/docs/keploy-cloud/deduplication/) — related test-stability feature. - [Static Deduplication](/docs/keploy-cloud/static-deduplication/) — dedupe recorded tests. -- [Mock Registry](/docs/keploy-cloud/mock-registry/) — manage the mocks time-freezing relies on. +- [Mock Registry](/docs/universal-mocker/mock-registry/) — manage the mocks time-freezing relies on. diff --git a/versioned_docs/version-4.0.0/keploy-explained/integrations-vscode.md b/versioned_docs/version-4.0.0/keploy-explained/integrations-vscode.md index fdacfa063..4fada6629 100644 --- a/versioned_docs/version-4.0.0/keploy-explained/integrations-vscode.md +++ b/versioned_docs/version-4.0.0/keploy-explained/integrations-vscode.md @@ -16,7 +16,7 @@ keywords: # IDE integrations — VS Code -Keploy's VS Code extension, **Keploy: API & DB Mocks**, sets up the [`keploy mock`](/docs/running-keploy/mock-your-tests/) loop through the coding agent you already use. Keploy records the real calls your tests make to APIs and databases, then replays your tests with those dependencies switched off. The extension installs the Keploy CLI for you, signs you in, installs Keploy's skill for your project, and hands the setup to Claude Code, GitHub Copilot or Cursor's agent. It then shows what the CLI reports about each test, and stages the setup's files for you to commit. +Keploy's VS Code extension, **Keploy: API & DB Mocks**, sets up the [`keploy mock`](/docs/universal-mocker/mock-your-tests/) loop through the coding agent you already use. Keploy records the real calls your tests make to APIs and databases, then replays your tests with those dependencies switched off. The extension installs the Keploy CLI for you, signs you in, installs Keploy's skill for your project, and hands the setup to Claude Code, GitHub Copilot or Cursor's agent. It then shows what the CLI reports about each test, and stages the setup's files for you to commit. Install it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=keploy.keployio), then follow the [VS Code extension guide](/docs/running-keploy/utg-vscode-extension/). @@ -29,7 +29,7 @@ If you need Keploy in JetBrains, Neovim, or another editor, [tell our team](mail ## Related - [Keploy VS Code extension](/docs/running-keploy/utg-vscode-extension/) — install, sign in, set up with your agent, and troubleshoot. -- [Mock your tests](/docs/running-keploy/mock-your-tests/) — the `keploy mock` commands your agent runs. +- [Mock your tests](/docs/universal-mocker/mock-your-tests/) — the `keploy mock` commands your agent runs. - [SCM Integrations — PR Agent](/docs/keploy-explained/integrations-pr-agent/) — the pull-request integration. - [Keploy Troubleshooting Guide](/docs/keploy-explained/common-errors/) — fix common setup issues. - [What is Keploy?](/docs/keploy-explained/introduction/) — project overview. diff --git a/versioned_docs/version-4.0.0/running-keploy/cli-commands.md b/versioned_docs/version-4.0.0/running-keploy/cli-commands.md index bf9297560..c1ca037a8 100755 --- a/versioned_docs/version-4.0.0/running-keploy/cli-commands.md +++ b/versioned_docs/version-4.0.0/running-keploy/cli-commands.md @@ -442,7 +442,7 @@ keploy example [flags] ## [mock](#mock) -`keploy mock` records the calls your own test suite makes to its dependencies, and replays them so the suite runs with the dependencies off. See [Mock your tests](/docs/running-keploy/mock-your-tests/) for the whole flow. +`keploy mock` records the calls your own test suite makes to its dependencies, and replays them so the suite runs with the dependencies off. See [Mock your tests](/docs/universal-mocker/mock-your-tests/) for the whole flow. Usage: @@ -469,7 +469,7 @@ With `KEPLOY_PROVEN=1` set, `keploy mock record` also judges every test it recor | `keploy mock check` | Reads the recordings offline and names each mistake a hand edit made, with its file, line and fix. | | `keploy mock judge` | Judges the recordings again, for example after a Keploy upgrade. | -See [Prove each test offline](/docs/running-keploy/mock-your-tests/#proven). +See [Prove each test offline](/docs/universal-mocker/mock-your-tests/#proven). ## [login](#login) diff --git a/versioned_docs/version-4.0.0/running-keploy/utg-vsc-extension.md b/versioned_docs/version-4.0.0/running-keploy/utg-vsc-extension.md index 433044399..241eb4c9a 100644 --- a/versioned_docs/version-4.0.0/running-keploy/utg-vsc-extension.md +++ b/versioned_docs/version-4.0.0/running-keploy/utg-vsc-extension.md @@ -23,7 +23,7 @@ keywords: The **Keploy VS Code extension** (listed as **Keploy: API & DB Mocks**, ID `keploy.keployio`) sets Keploy up for your tests through the coding agent you already use. Keploy records the real calls each of your tests makes to its dependencies, such as HTTP and gRPC APIs, databases, caches and queues, and replays them from the recording, so the same suite runs green with none of those dependencies contacted, on your laptop and in CI. -The extension doesn't write your tests or your integration. It installs the Keploy CLI, signs you in, installs Keploy's skill for your project, and hands the setup to your agent. Your agent then runs the CLI's [`keploy mock`](/docs/running-keploy/mock-your-tests/) commands, and the extension shows what the CLI reports about each test. +The extension doesn't write your tests or your integration. It installs the Keploy CLI, signs you in, installs Keploy's skill for your project, and hands the setup to your agent. Your agent then runs the CLI's [`keploy mock`](/docs/universal-mocker/mock-your-tests/) commands, and the extension shows what the CLI reports about each test. :::note Version 3.1.0 hands the setup to your agent @@ -206,6 +206,6 @@ On Linux, if the CLI doesn't run at all, check your glibc version with `ldd --ve ## Related -- [Mock your tests](/docs/running-keploy/mock-your-tests/) — the `keploy mock` commands your agent runs. +- [Mock your tests](/docs/universal-mocker/mock-your-tests/) — the `keploy mock` commands your agent runs. - [Keploy on macOS](/docs/installation/macos-installation/) and [Linux](/docs/installation/linux-installation/) — installing the CLI yourself, and what each platform supports. - [Keploy's PR Agent](/docs/running-keploy/utg-pr-agent/) — Keploy's unit test generator, on your pull requests. diff --git a/versioned_docs/version-4.0.0/server/installation.md b/versioned_docs/version-4.0.0/server/installation.md index 4331ba528..e081e7989 100644 --- a/versioned_docs/version-4.0.0/server/installation.md +++ b/versioned_docs/version-4.0.0/server/installation.md @@ -72,7 +72,7 @@ It runs natively, with no VM and no Docker: :::tip Want to mock your test suite instead? -To record the calls your existing tests make, with no app to start and no requests to send, see [Mock your tests](/docs/running-keploy/mock-quickstart/). +To record the calls your existing tests make, with no app to start and no requests to send, see [Mock your tests](/docs/universal-mocker/mock-quickstart/). ::: @@ -164,7 +164,7 @@ To replay the tests on every pull request, see [GitHub Actions](/docs/ci-cd/gith ## Related -- [Mock your tests](/docs/running-keploy/mock-your-tests/): record and replay the calls your test suite makes. +- [Mock your tests](/docs/universal-mocker/mock-your-tests/): record and replay the calls your test suite makes. - [Installing Keploy on Linux](/docs/installation/linux-installation/). - [Installing Keploy on macOS](/docs/installation/macos-installation/): Apple silicon, natively or with Docker. - [Installing Keploy on Windows](/docs/installation/windows-installation/): native on x86-64, or WSL/Docker. diff --git a/versioned_docs/version-4.0.0/running-keploy/mock-quickstart.md b/versioned_docs/version-4.0.0/universal-mocker/mock-quickstart.md similarity index 100% rename from versioned_docs/version-4.0.0/running-keploy/mock-quickstart.md rename to versioned_docs/version-4.0.0/universal-mocker/mock-quickstart.md diff --git a/versioned_docs/version-4.0.0/keploy-cloud/mock-registry.md b/versioned_docs/version-4.0.0/universal-mocker/mock-registry.md similarity index 100% rename from versioned_docs/version-4.0.0/keploy-cloud/mock-registry.md rename to versioned_docs/version-4.0.0/universal-mocker/mock-registry.md diff --git a/versioned_docs/version-4.0.0/running-keploy/mock-your-tests.md b/versioned_docs/version-4.0.0/universal-mocker/mock-your-tests.md similarity index 100% rename from versioned_docs/version-4.0.0/running-keploy/mock-your-tests.md rename to versioned_docs/version-4.0.0/universal-mocker/mock-your-tests.md diff --git a/versioned_docs/version-4.0.0/universal-mocker/overview.md b/versioned_docs/version-4.0.0/universal-mocker/overview.md new file mode 100644 index 000000000..1581e3e04 --- /dev/null +++ b/versioned_docs/version-4.0.0/universal-mocker/overview.md @@ -0,0 +1,127 @@ +--- +id: overview +title: Universal Mocker — service virtualization for the tests you already have +sidebar_label: Overview +description: Keploy's Universal Mocker records the database, queue and API calls your own test suite makes, then replays them so go test, pytest, Jest, JUnit or Playwright runs with those dependencies switched off. Service virtualization with no mock code to write. +tags: + - universal mocker + - service virtualization + - mocks + - mocking + - keploy mock +keywords: + - universal mocker + - service virtualization + - dependency mocking + - keploy mock record + - keploy mock replay + - mock database calls + - offline tests +--- + +# Universal Mocker + +**Universal Mocker** is Keploy's service virtualization for the tests you +already have. You run your own test command under `keploy mock record` once, +with the real dependencies up. Keploy saves every call your tests make to +databases, queues and other services, with each answer. After that, +`keploy mock replay` runs the same command with those dependencies switched off +and answers each call from the recording. + +You write no mock code, and you change no test. Your test framework still +decides which tests pass. + +![Record once against the real dependencies, then replay with them switched off](/img/universal-mocker/record-replay.svg) + +## Understand how it works + +1. **Record.** Run `keploy mock record -c ""`. Your tests run + against the real dependencies. Keploy sits between the two and saves each + outgoing call and its answer. +2. **Replay.** Run `keploy mock replay -c ""`. The + dependencies can be off. Keploy answers each call with its recorded answer. + By default, a call that matches no recording fails the run + (`--on-miss fail`), so a missing mock never passes silently. +3. **Check every test on its own (optional).** With `KEPLOY_PROVEN=1`, + `keploy mock record` also replays each test with the dependencies off before + it keeps the recording. A test that doesn't replay is set aside, with the + reason and the next step. See + [Prove each test offline](./mock-your-tests.md#proven). +4. **Share.** In that mode, the recordings go to Keploy Cloud, under a Keploy + branch named after your git branch. Your repository holds only `keploy.yml` + and `keploy.lock`, which pins each test to its recordings. CI replays what + `keploy.lock` pins. + +## Choose the right Keploy product + +| You want to… | Use | +| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | +| Run the tests you already have (unit, integration, e2e) without their databases, queues and APIs | **Universal Mocker** (`keploy mock`) | +| Turn real traffic from a running app or a cluster into tests and mocks | [Integration Testing](/docs/server/install/) (`keploy record`, k8s-proxy) | +| Generate API tests from a schema, a collection or live traffic with AI | [API Testing](/docs/running-keploy/api-test-generator/) | + +The difference is who owns the tests. With Universal Mocker, your team owns +the tests and records whenever a branch needs it. With Integration Testing, +Keploy captures tests from an environment's traffic. + +## Check what it supports + +**Test commands.** Any command that runs your tests: `go test`, `pytest`, +`npx jest`, `mvn test`, `npx playwright test`, or a shell script. Keploy wraps +the command and doesn't need to know the framework. + +**Per-test checks** (`KEPLOY_PROVEN=1`) need each test to say where it starts +and ends: + +- **Go:** [`github.com/keploy/go-sdk/v3`](https://pkg.go.dev/github.com/keploy/go-sdk/v3/keploytest). +- **Playwright:** [`@keploy/playwright`](https://www.npmjs.com/package/@keploy/playwright). +- **Any other framework:** two HTTP calls per test, as + [Per-test scoping](./mock-your-tests.md#per-test-scoping-optional) shows. + +**Platforms.** + +| Platform | Record and replay | Per-test checks (`KEPLOY_PROVEN=1`) | Notes | +| --------------------- | ----------------- | ----------------------------------- | -------------------------------------------------------- | +| Linux | Yes | Yes | Keploy's agent runs as root; Keploy starts it with sudo. | +| macOS (Apple silicon) | Yes | Yes | No sudo or admin rights needed. | +| Docker | Yes | Not yet | Pass a `docker run` or `docker compose` command. | +| Windows (x86-64) | Yes | Coming soon | The VS Code flow on Windows is coming soon too. | + +**Dependencies** in Keploy 3.9.3. "Docker" means: run the tests through a +Docker command so Keploy reads the calls on Linux. + +| Dependency | Linux | macOS | +| ---------------------------------- | ----- | ------ | +| HTTP and HTTPS, HTTP/2 | Yes | Yes | +| gRPC | Yes | Yes | +| PostgreSQL | Yes | Yes | +| MySQL | Yes | Yes | +| MongoDB | Yes | Yes | +| Amazon DynamoDB | Yes | Yes | +| Aerospike | Yes | Yes | +| Redis | Yes | Docker | +| Kafka | Yes | Docker | +| Memcached | Yes | Docker | +| Apache Pulsar | Yes | Docker | +| Amazon SQS | Yes | Docker | +| Couchbase, HBase, Apache ZooKeeper | Yes | Docker | + +A call to any other TCP service is saved as raw bytes. It replays only when +your tests send exactly the same bytes again. + +## Use it from VS Code + +The [Keploy VS Code extension](/docs/running-keploy/utg-vscode-extension/) +installs the Keploy CLI, signs you in, and hands the project setup to your +coding agent. Then you record, replay and review from the editor. + +## Next steps + +- [Mock your tests in 2 minutes](./mock-quickstart.md): a copy-paste walkthrough + with a sample app. +- [Mock your own tests](./mock-your-tests.md): every option, per-test checks, + CI, and sharing with your team. +- [Mock Registry](./mock-registry.md): keep mocks in Keploy Cloud instead of + your repository. +- [CLI commands](/docs/running-keploy/cli-commands/): the full `keploy` command + list. diff --git a/versioned_sidebars/version-4.0.0-sidebars.json b/versioned_sidebars/version-4.0.0-sidebars.json index 259ce940e..725542740 100644 --- a/versioned_sidebars/version-4.0.0-sidebars.json +++ b/versioned_sidebars/version-4.0.0-sidebars.json @@ -68,14 +68,9 @@ "running-keploy/configuration-file", "running-keploy/recording-filters", "running-keploy/custom-mocks", - "running-keploy/mock-quickstart", - - "running-keploy/mock-your-tests", - "running-keploy/utg-vscode-extension", "running-keploy/keploy-templatize", "running-keploy/risk-profile-analysis", "keploy-cloud/time-freezing", - "keploy-cloud/mock-registry", "keploy-cloud/keploy-console", "keploy-cloud/auto-test-generation", "keploy-cloud/deduplication", @@ -253,6 +248,35 @@ } ] }, + { + "type": "category", + "label": "Universal Mocker", + "collapsed": true, + "link": { + "type": "doc", + "id": "universal-mocker/overview" + }, + "items": [ + { + "type": "category", + "label": "Quickstarts", + "collapsible": true, + "collapsed": false, + "items": ["universal-mocker/mock-quickstart"] + }, + { + "type": "category", + "label": "Guides", + "collapsible": true, + "collapsed": false, + "items": [ + "universal-mocker/mock-your-tests", + "running-keploy/utg-vscode-extension", + "universal-mocker/mock-registry" + ] + } + ] + }, { "type": "category", "label": "UI Testing", From 489e211363504d833abbb4fa9c3b07d001645670 Mon Sep 17 00:00:00 2001 From: slayerjain Date: Fri, 20 Nov 2026 00:14:33 +0530 Subject: [PATCH 2/4] docs: add a Go quickstart to the Universal Mocker section A copy-paste Go package whose tests read PostgreSQL and call an HTTP rates API. It records the calls with keploy mock record --local, replays them with both dependencies off, shows the miss a new test makes, and then checks each test on its own with KEPLOY_PROVEN=1 and keploytest. Every output is from a real run of Keploy 3.9.3 on Linux. Also: - a Universal Mocker card on the docs home and an icon for its sidebar category (SidebarCategoryIcon.js is reformatted by prettier 2.8.8, which CI runs on every changed file); - the installation pages link Mock your tests at its new URL. Signed-off-by: slayerjain --- src/components/Product.js | 27 +- src/components/SidebarCategoryIcon.js | 100 ++-- .../version-4.0.0/installation/linux.md | 2 +- .../version-4.0.0/installation/macos.md | 2 +- .../version-4.0.0/installation/windows.md | 2 +- .../universal-mocker/overview.md | 4 +- .../universal-mocker/quickstarts/go.md | 562 ++++++++++++++++++ .../version-4.0.0-sidebars.json | 5 +- 8 files changed, 648 insertions(+), 56 deletions(-) create mode 100644 versioned_docs/version-4.0.0/universal-mocker/quickstarts/go.md diff --git a/src/components/Product.js b/src/components/Product.js index 190f8ccc5..3580610d9 100644 --- a/src/components/Product.js +++ b/src/components/Product.js @@ -1,6 +1,7 @@ import React from "react"; import Link from "@docusaurus/Link"; import useBaseUrl from "@docusaurus/useBaseUrl"; +import {FaLayerGroup} from "react-icons/fa"; function UTG() { return ( @@ -232,6 +233,30 @@ function UTG() { +
  • + +
    +
    +
    +
      +
    • +

      + Service virtualization for the tests you already have: + replays their database and API calls offline. +

      +
    • +
    +
    + +
  • ); @@ -244,7 +269,7 @@ export const Products = () => { Products 🛠️

    - Keploy provides three key products that help you streamline your testing + Keploy provides four key products that help you streamline your testing workflow:

    diff --git a/src/components/SidebarCategoryIcon.js b/src/components/SidebarCategoryIcon.js index 6f86cd34b..beb269732 100644 --- a/src/components/SidebarCategoryIcon.js +++ b/src/components/SidebarCategoryIcon.js @@ -1,4 +1,4 @@ -import React from 'react'; +import React from "react"; import { FaBook, FaRocket, @@ -17,12 +17,8 @@ import { FaProjectDiagram, FaChartLine, FaLock, -} from 'react-icons/fa'; -import { - SiKubernetes, - SiDocker, - SiGithubactions -} from 'react-icons/si'; +} from "react-icons/fa"; +import {SiKubernetes, SiDocker, SiGithubactions} from "react-icons/si"; /** * SidebarCategoryIcon - Icon component for sidebar top-level categories @@ -34,52 +30,57 @@ import { const categoryIcons = { // Main categories - 'integration-testing': FaPlug, - 'api-testing': FaRocket, - 'keploy-cloud': FaCloud, - 'quickstart': FaRocket, - 'quickstarts': FaRocket, - 'concepts': FaLightbulb, - 'explanation': FaBook, - 'installation': FaTerminal, - 'configuration': FaCog, - 'running-keploy': FaTerminal, - 'ci-cd': SiGithubactions, - 'security': FaShieldAlt, - 'operation': FaTools, + "integration-testing": FaPlug, + "api-testing": FaRocket, + "universal-mocker": FaLayerGroup, + "keploy-cloud": FaCloud, + quickstart: FaRocket, + quickstarts: FaRocket, + concepts: FaLightbulb, + explanation: FaBook, + installation: FaTerminal, + configuration: FaCog, + "running-keploy": FaTerminal, + "ci-cd": SiGithubactions, + security: FaShieldAlt, + operation: FaTools, // Language/Framework categories - 'java': FaCode, - 'golang': FaCode, - 'python': FaCode, - 'javascript': FaCode, - 'typescript': FaCode, + java: FaCode, + golang: FaCode, + python: FaCode, + javascript: FaCode, + typescript: FaCode, // Infrastructure - 'docker': SiDocker, - 'kubernetes': SiKubernetes, - 'k8s': SiKubernetes, + docker: SiDocker, + kubernetes: SiKubernetes, + k8s: SiKubernetes, // Features - 'mocking': FaDatabase, - 'mock-registry': FaLayerGroup, - 'deduplication': FaProjectDiagram, - 'test-generation': FaChartLine, + mocking: FaDatabase, + "mock-registry": FaLayerGroup, + deduplication: FaProjectDiagram, + "test-generation": FaChartLine, // Other - 'server': FaServer, - 'gsoc': FaGraduationCap, - 'hacktoberfest': FaGraduationCap, - 'enterprise': FaLock, - 'dependencies': FaLayerGroup, + server: FaServer, + gsoc: FaGraduationCap, + hacktoberfest: FaGraduationCap, + enterprise: FaLock, + dependencies: FaLayerGroup, }; export function getCategoryIcon(categoryLabel) { - const key = categoryLabel.toLowerCase().replace(/\s+/g, '-'); + const key = categoryLabel.toLowerCase().replace(/\s+/g, "-"); return categoryIcons[key] || null; } -export default function SidebarCategoryIcon({ category, size = 16, className = '' }) { +export default function SidebarCategoryIcon({ + category, + size = 16, + className = "", +}) { const Icon = getCategoryIcon(category); if (!Icon) return null; @@ -88,15 +89,15 @@ export default function SidebarCategoryIcon({ category, size = 16, className = ' @@ -112,5 +113,4 @@ export default function SidebarCategoryIcon({ category, size = 16, className = ' } // Export icon mapping for use in sidebar configuration -export { categoryIcons }; - +export {categoryIcons}; diff --git a/versioned_docs/version-4.0.0/installation/linux.md b/versioned_docs/version-4.0.0/installation/linux.md index 7777a53b8..e5693972d 100644 --- a/versioned_docs/version-4.0.0/installation/linux.md +++ b/versioned_docs/version-4.0.0/installation/linux.md @@ -34,7 +34,7 @@ source /dev/stdin <<<"$(curl -fsSL https://keploy.io/install.sh || echo 'echo Ke - **No browser available** (a remote shell, a container): run with `--manual-login` and paste an API key from your Keploy dashboard when prompted. - **CI, or any non-interactive run**: set `KEPLOY_API_KEY` (or pass `--api-key`) and Keploy skips the sign-in prompt entirely. -- **Offline**: the local mock loop — `keploy mock record --local` and `keploy mock replay --local` — is the one pair that runs without signing in. While you are signed out it logs a harmless `failed to validate user role` line and then runs normally. This is the mock loop, not a replacement for `keploy record` and `keploy test` — see [Mock your tests](/docs/running-keploy/mock-your-tests). +- **Offline**: the local mock loop — `keploy mock record --local` and `keploy mock replay --local` — is the one pair that runs without signing in. While you are signed out it logs a harmless `failed to validate user role` line and then runs normally. This is the mock loop, not a replacement for `keploy record` and `keploy test` — see [Mock your tests](/docs/universal-mocker/mock-your-tests/). A free account is enough to record and replay. Free-tier runs are subject to a usage allowance. diff --git a/versioned_docs/version-4.0.0/installation/macos.md b/versioned_docs/version-4.0.0/installation/macos.md index b0b5a7297..4f96f38b8 100644 --- a/versioned_docs/version-4.0.0/installation/macos.md +++ b/versioned_docs/version-4.0.0/installation/macos.md @@ -24,7 +24,7 @@ Native macOS support covers **Go, Node.js, Python and Java** apps, including the - **No browser available** (a remote shell, a container): run with `--manual-login` and paste an API key from your Keploy dashboard when prompted. - **CI, or any non-interactive run**: set `KEPLOY_API_KEY` (or pass `--api-key`) and Keploy skips the sign-in prompt entirely. -- **Offline**: the local mock loop — `keploy mock record --local` and `keploy mock replay --local` — is the one pair that runs without signing in. While you are signed out it logs a harmless `failed to validate user role` line and then runs normally. This is the mock loop, not a replacement for `keploy record` and `keploy test` — see [Mock your tests](/docs/running-keploy/mock-your-tests). +- **Offline**: the local mock loop — `keploy mock record --local` and `keploy mock replay --local` — is the one pair that runs without signing in. While you are signed out it logs a harmless `failed to validate user role` line and then runs normally. This is the mock loop, not a replacement for `keploy record` and `keploy test` — see [Mock your tests](/docs/universal-mocker/mock-your-tests/). A free account is enough to record and replay. Free-tier runs are subject to a usage allowance. diff --git a/versioned_docs/version-4.0.0/installation/windows.md b/versioned_docs/version-4.0.0/installation/windows.md index a6528ad24..03258dc70 100644 --- a/versioned_docs/version-4.0.0/installation/windows.md +++ b/versioned_docs/version-4.0.0/installation/windows.md @@ -27,7 +27,7 @@ Native Windows support covers apps in **Go, Node.js, Python and Java**, and unde - **No browser available** (a remote shell, a container): run with `--manual-login` and paste an API key from your Keploy dashboard when prompted. - **CI, or any non-interactive run**: set `KEPLOY_API_KEY` (or pass `--api-key`) and Keploy skips the sign-in prompt entirely. -- **Offline**: the local mock loop — `keploy mock record --local` and `keploy mock replay --local` — is the one pair that runs without signing in. While you are signed out it logs a harmless `failed to validate user role` line and then runs normally. This is the mock loop, not a replacement for `keploy record` and `keploy test` — see [Mock your tests](/docs/running-keploy/mock-your-tests). +- **Offline**: the local mock loop — `keploy mock record --local` and `keploy mock replay --local` — is the one pair that runs without signing in. While you are signed out it logs a harmless `failed to validate user role` line and then runs normally. This is the mock loop, not a replacement for `keploy record` and `keploy test` — see [Mock your tests](/docs/universal-mocker/mock-your-tests/). A free account is enough to record and replay. Free-tier runs are subject to a usage allowance. diff --git a/versioned_docs/version-4.0.0/universal-mocker/overview.md b/versioned_docs/version-4.0.0/universal-mocker/overview.md index 1581e3e04..9b43d4aac 100644 --- a/versioned_docs/version-4.0.0/universal-mocker/overview.md +++ b/versioned_docs/version-4.0.0/universal-mocker/overview.md @@ -117,8 +117,10 @@ coding agent. Then you record, replay and review from the editor. ## Next steps +- [Go quickstart](./quickstarts/go.md): run `go test` without PostgreSQL or an + HTTP API, then check each test on its own. - [Mock your tests in 2 minutes](./mock-quickstart.md): a copy-paste walkthrough - with a sample app. + with a Python sample app. - [Mock your own tests](./mock-your-tests.md): every option, per-test checks, CI, and sharing with your team. - [Mock Registry](./mock-registry.md): keep mocks in Keploy Cloud instead of diff --git a/versioned_docs/version-4.0.0/universal-mocker/quickstarts/go.md b/versioned_docs/version-4.0.0/universal-mocker/quickstarts/go.md new file mode 100644 index 000000000..d31639724 --- /dev/null +++ b/versioned_docs/version-4.0.0/universal-mocker/quickstarts/go.md @@ -0,0 +1,562 @@ +--- +id: go +title: "Go quickstart: run go test without PostgreSQL or an HTTP API" +sidebar_label: Go (go test) +description: Record the PostgreSQL queries and HTTP calls a Go test suite makes with keploy mock record, then run the same go test with both dependencies switched off. A copy-paste sample with the real output of each step. +tags: + - universal mocker + - service virtualization + - go + - quickstart +keywords: + - keploy mock go + - go test mock postgres + - mock http api go test + - service virtualization go + - keploytest +--- + +# Go quickstart: run go test without PostgreSQL or an HTTP API + +In this quickstart, you build a small Go package whose tests read PostgreSQL +and call an exchange-rates API. You record those calls once, with both +dependencies up. Then you run the same `go test` with both of them switched +off, and the tests still pass. + +You don't write any mock code, and the tests don't change. + +Every output on this page comes from a real run of Keploy 3.9.3 on Linux. Long +log lines are trimmed and timestamps are removed. + +## Before you begin + +You need: + +- Linux, or macOS on Apple silicon. On Linux, Keploy's agent runs as root, so + Keploy may ask for your `sudo` password. +- [Go](https://go.dev/dl/) 1.21 or newer. +- [Docker](https://docs.docker.com/get-docker/), to run PostgreSQL. +- Keploy. To install it, run: + + ```bash + source /dev/stdin <<<"$(curl -fsSL https://keploy.io/install.sh || echo 'echo Keploy installer download failed >&2; return 1')" + ``` + + For other ways to install it, see [Installation](/docs/server/installation/). + +## Step 1: Create the sample package + +1. Create a folder and a Go module: + + ```bash + mkdir orders && cd orders + go mod init example.com/orders + ``` + +2. Save this as `orders.go`. `TotalIn` reads an order from PostgreSQL, asks the + rates API for an exchange rate, and returns the converted total: + + ```go + // Package orders prices an order in another currency. The order comes from + // PostgreSQL and the exchange rate from a rates API. + package orders + + import ( + "context" + "database/sql" + "encoding/json" + "fmt" + "net/http" + ) + + type Service struct { + DB *sql.DB + RatesURL string + } + + // TotalIn returns the order's total, converted to currency. + func (s *Service) TotalIn(ctx context.Context, orderID int, currency string) (float64, error) { + var cents int + var from string + err := s.DB.QueryRowContext(ctx, + "SELECT amount_cents, currency FROM orders WHERE id = $1", orderID).Scan(¢s, &from) + if err != nil { + return 0, fmt.Errorf("order %d: %w", orderID, err) + } + + url := fmt.Sprintf("%s/rates?from=%s&to=%s", s.RatesURL, from, currency) + req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil) + if err != nil { + return 0, err + } + resp, err := http.DefaultClient.Do(req) + if err != nil { + return 0, err + } + defer resp.Body.Close() + if resp.StatusCode != http.StatusOK { + return 0, fmt.Errorf("rates API: %s", resp.Status) + } + var rate struct { + Rate float64 `json:"rate"` + } + if err := json.NewDecoder(resp.Body).Decode(&rate); err != nil { + return 0, err + } + return float64(cents) / 100 * rate.Rate, nil + } + ``` + +3. Save this as `orders_test.go`. Each test creates the table and its rows, + then checks one total: + + ```go + package orders + + import ( + "context" + "database/sql" + "testing" + + _ "github.com/lib/pq" + ) + + func newService(t *testing.T) *Service { + db, err := sql.Open("postgres", + "postgres://postgres:postgres@localhost:5432/postgres?sslmode=disable") + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { db.Close() }) + + _, err = db.Exec(`CREATE TABLE IF NOT EXISTS orders ( + id int PRIMARY KEY, amount_cents int NOT NULL, currency text NOT NULL)`) + if err != nil { + t.Fatal(err) + } + _, err = db.Exec(`INSERT INTO orders VALUES (1, 4000, 'EUR'), (2, 1250, 'USD') + ON CONFLICT (id) DO NOTHING`) + if err != nil { + t.Fatal(err) + } + return &Service{DB: db, RatesURL: "http://localhost:8090"} + } + + func TestTotalInUSD(t *testing.T) { + s := newService(t) + got, err := s.TotalIn(context.Background(), 1, "USD") + if err != nil { + t.Fatal(err) + } + if got != 50 { + t.Fatalf("total = %v, want 50", got) + } + } + + func TestTotalInEUR(t *testing.T) { + s := newService(t) + got, err := s.TotalIn(context.Background(), 2, "EUR") + if err != nil { + t.Fatal(err) + } + if got != 10 { + t.Fatalf("total = %v, want 10", got) + } + } + ``` + +4. Save this as `cmd/rates/main.go`. It stands in for a real exchange-rates + API: + + ```go + // A stand-in for a real exchange-rates API. + package main + + import ( + "encoding/json" + "log" + "net/http" + ) + + var rates = map[string]float64{"EUR-USD": 1.25, "USD-EUR": 0.8, "EUR-GBP": 0.875} + + func main() { + http.HandleFunc("/rates", func(w http.ResponseWriter, r *http.Request) { + pair := r.URL.Query().Get("from") + "-" + r.URL.Query().Get("to") + rate, ok := rates[pair] + if !ok { + http.Error(w, "unknown pair "+pair, http.StatusNotFound) + return + } + json.NewEncoder(w).Encode(map[string]float64{"rate": rate}) + }) + log.Println("rates API on :8090") + log.Fatal(http.ListenAndServe(":8090", nil)) + } + ``` + +5. Add the PostgreSQL driver: + + ```bash + go get github.com/lib/pq@v1.10.9 + go mod tidy + ``` + +## Step 2: Run the tests against the real dependencies + +1. Start PostgreSQL: + + ```bash + docker run -d --name orders-db -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:16 + ``` + +2. In a second terminal, in the `orders` folder, start the rates API: + + ```bash + go run ./cmd/rates + ``` + +3. Back in the first terminal, run the tests: + + ```bash + go test -count=1 ./... + ``` + + ``` + ok example.com/orders 0.031s + ? example.com/orders/cmd/rates [no test files] + ``` + +`-count=1` turns off Go's test cache. Without it, `go test` can print a cached +result and skip the tests, and then there are no calls to record or replay. + +## Step 3: Record the calls + +Run the same test command under `keploy mock record`: + +```bash +keploy mock record --local -c "go test -count=1 ./..." +``` + +``` +🐰 Keploy: INFO Recording mocks for your test command {"mock-set": "default", "program": "go", "args": 3} +🐰 Keploy: INFO Starting Application : {"program": "go", "args": 3} +ok example.com/orders 0.035s +? example.com/orders/cmd/rates [no test files] +🐰 Keploy: INFO recorded mocks {"mocks": 10, "mock-set": "default"} +🐰 Keploy: INFO test command finished successfully {"phase": "record"} +``` + +`--local` keeps the recording in your repository, so you don't need a Keploy +account for this quickstart. Without `--local`, Keploy asks you to sign in +first. + +Keploy wrote two things: + +- `keploy.yml`, the project's Keploy settings. It holds the app name and the + test command. +- `keploy/default/mocks.yaml`, the recording: 10 mocks, 8 for PostgreSQL (the + connections and each statement) and 2 HTTP calls, each with its answer. + +Here is one HTTP call from `mocks.yaml`, trimmed: + +```yaml +kind: Http +name: mock-4 +spec: + metadata: + destAddr: "[::1]:8090" + operation: GET + type: HTTP_CLIENT + req: + method: GET + url: /rates?from=EUR&to=USD + header: + Host: localhost:8090 + resp: + status_code: 200 + body: | + {"rate":1.25} +``` + +## Step 4: Replay with the dependencies off + +1. Stop PostgreSQL: + + ```bash + docker rm -f orders-db + ``` + +2. Stop the rates API with Ctrl+C in the second terminal. + +3. Run the tests on their own. They fail, because nothing answers: + + ```bash + go test -count=1 ./... + ``` + + ``` + orders_test.go:22: dial tcp [::1]:5432: connect: connection refused + FAIL + FAIL example.com/orders 0.005s + ``` + +4. Run them under `keploy mock replay`: + + ```bash + keploy mock replay --local -c "go test -count=1 ./..." + ``` + + ``` + 🐰 Keploy: INFO Replaying mocks for your test command {"mock-set": "default", "program": "go", "args": 3, "on-miss": "fail"} + 🐰 Keploy: INFO Starting Application : {"program": "go", "args": 3} + ok example.com/orders 0.163s + ? example.com/orders/cmd/rates [no test files] + 🐰 Keploy: INFO mock replay summary {"loaded": 10, "consumed": 8, "missed": 0} + 🐰 Keploy: INFO test command finished successfully {"phase": "replay"} + 🐰 Keploy: INFO this replay ran with every dependency answered from the recording {"mock-set": "default", "served": 8} + ``` + +The tests pass with no database and no rates API running. Keploy answered every +call from the recording. + +## Step 5: Add a test, and see a call with no recording + +1. Add this test at the end of `orders_test.go`: + + ```go + func TestTotalInGBP(t *testing.T) { + s := newService(t) + got, err := s.TotalIn(context.Background(), 1, "GBP") + if err != nil { + t.Fatal(err) + } + if got != 35 { + t.Fatalf("total = %v, want 35", got) + } + } + ``` + +2. Replay again, with the dependencies still off: + + ```bash + keploy mock replay --local -c "go test -count=1 ./..." + ``` + + ``` + --- FAIL: TestTotalInGBP (0.02s) + orders_test.go:27: pq: keploy-pg-v3: no recorded invocation matched (hash=…e6592f0c76da currentTest= binds=6); … + FAIL + FAIL example.com/orders 0.228s + 🐰 Keploy: INFO mock replay summary {"loaded": 10, "consumed": 8, "missed": 1} + Mock mismatch: [PostgreSQL] INSERT INTO orders VALUES ($1, $2, $3), ($4, $5, $6) + ON CONFLICT (id) DO NOTHING → [::1]:5432 + Hint: The 2 recorded invocation(s) of this SQL available at this point of the run were all already served: the application ran it more times here than the recording holds. If the extra call is intended, re-record the mock set with 'keploy mock record'; otherwise find what makes the application repeat it. + 🐰 Keploy: INFO test command exited non-zero; mirroring its exit code {"phase": "replay", "exitCode": 1} + ``` + + The new test runs the `INSERT` a third time, and the recording holds it + twice. Keploy doesn't send the call to the real database. It fails the run, + names the call, and says what to do. The exit code is the test command's, so + CI fails too. + +3. Start the dependencies again, as in [Step 2](#step-2-run-the-tests-against-the-real-dependencies), + and record again: + + ```bash + keploy mock record --local -c "go test -count=1 ./..." + ``` + + ``` + ok example.com/orders 0.088s + 🐰 Keploy: INFO recorded mocks {"mocks": 15, "mock-set": "default"} + 🐰 Keploy: INFO test command finished successfully {"phase": "record"} + ``` + + A new record replaces the set, so the recording always matches the tests + you have now. + +4. Stop the dependencies, as in Step 4, and replay: + + ```bash + keploy mock replay --local -c "go test -count=1 ./..." + ``` + + ``` + ok example.com/orders 0.221s + 🐰 Keploy: INFO mock replay summary {"loaded": 15, "consumed": 12, "missed": 0} + 🐰 Keploy: INFO this replay ran with every dependency answered from the recording {"mock-set": "default", "served": 12} + ``` + +## Step 6: Check each test on its own + +So far, Keploy answers the calls of the whole run. With `KEPLOY_PROVEN=1`, +it also knows where each test starts and ends. It then gives each test only the +calls that test recorded, replays every test before it keeps the recording, and +reports a result per test. + +1. Add Keploy's Go package: + + ```bash + go get github.com/keploy/go-sdk/v3@v3.1.3 + ``` + +2. In `orders_test.go`, import it, and make `defer keploytest.T(t)()` the first + line of each test: + + ```go + import ( + "context" + "database/sql" + "testing" + + "github.com/keploy/go-sdk/v3/keploytest" + _ "github.com/lib/pq" + ) + ``` + + ```go + func TestTotalInUSD(t *testing.T) { + defer keploytest.T(t)() + s := newService(t) + // ...the rest of the test is unchanged + } + ``` + + Do the same in `TestTotalInEUR` and `TestTotalInGBP`. Outside Keploy, the + line does nothing, so `go test` works as before. + +3. In `keploy.yml`, replace the `mock:` block with this one. It adds the command + Keploy runs the tests with: + + ```yaml + mock: + name: default + command: go test -p 1 -count=1 -json ./... + local: true + ``` + + `-p 1` runs one test binary at a time, which per-test checks need in this + release. `-json` shows each test's result, and the reason for a skip. + `local: true` keeps the recording in the repository, as `--local` did. + +4. Start the dependencies again, as in Step 2. Then delete the old recording, + and record: + + ```bash + rm -rf keploy + export KEPLOY_PROVEN=1 + keploy mock record + ``` + + ``` + 🐰 Keploy: INFO wrote per-test mock mappings {"tests": 3, "mock-set": "default"} + 🐰 Keploy: INFO recorded mocks {"mocks": 15, "mock-set": "default"} + 🐰 Keploy: INFO test command finished successfully {"phase": "record"} + keploy: judging round F (go test -p 1 -count=1 -json ./...): 3 passed, 0 failed, 0 skipped by the test, 0 skipped by keploy; its output: …/round-F.log + keploy: judging round C (go test -p 1 -count=1 -json ./...): 3 passed, 0 failed, 0 skipped by the test, 0 skipped by keploy; its output: …/round-C.log + keploy: committed keploy/default and its verdicts.yaml: 3 replayable, 0 quarantined + ``` + + After the record, Keploy replayed the tests twice with the dependencies off + (the judging rounds). All 3 replayed, so it kept all 3. A test that doesn't + replay is set aside in `keploy/default/verdicts.yaml`, with the reason and + the fix. + +5. Ask Keploy what to do next: + + ```bash + keploy mock status + ``` + + ``` + === KEPLOY NEXT === + phase: recorded + summary: 1 recording(s); not yet proven to run with the dependencies off: default (never replayed on this machine). + ask: Prove it offline? I'll replay the tests with every dependency switched off; any call the recording does not have fails the run. + run: KEPLOY_PROVEN=1 keploy mock replay --local -c 'go test -p 1 -count=1 -json ./...' --on-miss fail + ``` + + `keploy mock status` always prints a `NEXT` block like this one: where things + stand, and the command to run next. Coding agents read it too. + +6. Stop the dependencies, and replay: + + ```bash + keploy mock replay + ``` + + ``` + 🐰 Keploy: INFO mock replay summary {"loaded": 15, "consumed": 12, "missed": 0} + 🐰 Keploy: INFO this replay ran with every dependency answered from the recording {"mock-set": "default", "served": 12} + keploy: default: 3 test(s) ran: 3 passed, 0 failed (0 held by keploy), 0 skipped by the test; 0 quarantined (skipped by keploy) + 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) + MOCKED .::TestTotalInGBP: [::1]:5432 (mocked: if this is your app, start it from the runner, then re-record) + VERDICT passed + ``` + + Each `MOCKED` line names a connection a test opened that Keploy answered. + The EUR and GBP tests reuse the HTTP connection the USD test opened, so only + the USD test lists port 8090. + +7. Make a test fail on purpose. In `TestTotalInUSD`, change both `50`s to `51`, + then replay: + + ```bash + keploy mock replay + ``` + + ``` + keploy: default: 3 test(s) ran: 2 passed, 1 failed (0 held by keploy), 0 skipped by the test; 0 quarantined (skipped by keploy) + FAILED .::TestTotalInUSD: the test failed + VERDICT failed: the test command exited 1 + ``` + + Keploy names the test that failed, and exits with the test command's code. + Change the `51`s back to `50`. + +## Step 7: Commit the recording + +Commit `keploy.yml` and the `keploy/` folder with your code: + +```bash +git status --short +``` + +``` +?? cmd/rates/main.go +?? go.mod +?? go.sum +?? keploy.yml +?? keploy/.gitignore +?? keploy/default/README.md +?? keploy/default/last-record.yaml +?? keploy/default/mappings.yaml +?? keploy/default/mocks.yaml +?? keploy/default/verdicts.yaml +?? orders.go +?? orders_test.go +``` + +Keploy also writes `.keploy-run/`, with the logs of each run. Its own +`.gitignore` keeps it out of git. + +Now anyone can run `KEPLOY_PROVEN=1 keploy mock replay` on a clone, with no +PostgreSQL and no rates API, and CI can too. + +## Clean up + +```bash +docker rm -f orders-db +``` + +## Next steps + +- [Run the replay in CI, and share recordings with your team](../mock-your-tests.md#proven-ci). + With a Keploy account, recordings live in Keploy Cloud, and the repository + keeps only `keploy.yml` and `keploy.lock`. +- [Use the VS Code extension](/docs/running-keploy/utg-vscode-extension/) to + record and replay from your editor. +- [Learn every option of `keploy mock`](../mock-your-tests.md). diff --git a/versioned_sidebars/version-4.0.0-sidebars.json b/versioned_sidebars/version-4.0.0-sidebars.json index 725542740..9062c2f87 100644 --- a/versioned_sidebars/version-4.0.0-sidebars.json +++ b/versioned_sidebars/version-4.0.0-sidebars.json @@ -262,7 +262,10 @@ "label": "Quickstarts", "collapsible": true, "collapsed": false, - "items": ["universal-mocker/mock-quickstart"] + "items": [ + "universal-mocker/quickstarts/go", + "universal-mocker/mock-quickstart" + ] }, { "type": "category", From 5892d0a6269f451e33798c7873f5b85cfcace493 Mon Sep 17 00:00:00 2001 From: slayerjain Date: Fri, 20 Nov 2026 00:57:35 +0530 Subject: [PATCH 3/4] docs: list Universal Mocker on the docs home and check moved URLs - Docs home: Universal Mocker joins the "How do you want to get started?" entry points (GetStartedPaths), as a card across both columns, and the page's JSON-LD list built from the same data. The Products card added earlier is dropped: the home does not render it. - Mock Registry stays in Integration Testing, at its old URL: it documents how `keploy test` uploads mocks, not `keploy mock`. - Overview: Windows is coming, not supported yet. Sharing through Keploy Cloud needs a Keploy app in keploy.yml and a branch other than main. - Go quickstart: Linux only until it has run on macOS. Step 1 runs git init, Step 2 waits for PostgreSQL, Step 3 lists the four files Keploy writes, Step 6 says -json adds a line per test event, and Step 7 shows what git status prints. - Moved pages: macOS reads PostgreSQL, DynamoDB and Aerospike calls too; Windows is coming; the Python walkthrough records with --local. - Checks: a broken anchor now fails the build, and scripts/verify-moved-urls.js (yarn verify-moved-urls, run in CI) fails when a moved URL stops redirecting to its page. Signed-off-by: slayerjain --- .github/workflows/build_and_check.yml | 3 + docusaurus.config.js | 8 +- package.json | 1 + scripts/verify-moved-urls.js | 102 ++++++++++++++++++ src/components/GetStartedPaths.js | 85 ++++++++++++++- src/components/Product.js | 27 +---- src/pages/index.js | 2 +- .../keploy-cloud/keploy-console.md | 2 +- .../mock-registry.md | 0 .../keploy-cloud/time-freezing.md | 2 +- .../universal-mocker/mock-quickstart.md | 30 +++--- .../universal-mocker/mock-your-tests.md | 17 +-- .../universal-mocker/overview.md | 24 +++-- .../universal-mocker/quickstarts/go.md | 42 +++++--- .../version-4.0.0-sidebars.json | 4 +- 15 files changed, 264 insertions(+), 85 deletions(-) create mode 100644 scripts/verify-moved-urls.js rename versioned_docs/version-4.0.0/{universal-mocker => keploy-cloud}/mock-registry.md (100%) diff --git a/.github/workflows/build_and_check.yml b/.github/workflows/build_and_check.yml index 9f3f748ec..7f62a571f 100644 --- a/.github/workflows/build_and_check.yml +++ b/.github/workflows/build_and_check.yml @@ -69,6 +69,9 @@ jobs: - name: Verify every docs link the UI Capture SDK ships run: yarn verify-ui-capture-sdk-links + - name: Verify every moved docs URL still leads to its page + run: yarn verify-moved-urls + # Deploys this PR's build with main.yml's deploy script into a local S3, # then replays the weeks after it: no asset a live or open page still # loads is deleted, every unused one eventually is, and every file gets diff --git a/docusaurus.config.js b/docusaurus.config.js index 8809dd2ce..5ebd9fdc5 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -170,6 +170,10 @@ s.parentNode.insertBefore(b, s);})(window.lintrk);`, url: "https://keploy.io", baseUrl: "/docs/", onBrokenLinks: "throw", + // A link to a heading that does not exist fails the build too, as a + // broken link does: a page that moves or renames a heading must fix every + // link to it. + onBrokenAnchors: "throw", trailingSlash: true, markdown: { // Date each doc by the last commit that changed its content, not the last @@ -234,10 +238,6 @@ s.parentNode.insertBefore(b, s);})(window.lintrk);`, from: "/running-keploy/mock-your-tests/", to: "/universal-mocker/mock-your-tests/", }, - { - from: "/keploy-cloud/mock-registry/", - to: "/universal-mocker/mock-registry/", - }, ], }, ], diff --git a/package.json b/package.json index f9c335c94..9afeb9a5e 100644 --- a/package.json +++ b/package.json @@ -11,6 +11,7 @@ "verify-linkedin-tag": "node scripts/verify-linkedin-tag.js build", "verify-lastmod": "node scripts/verify-lastmod.js build", "verify-ui-capture-sdk-links": "node scripts/verify-ui-capture-sdk-links.js build", + "verify-moved-urls": "node scripts/verify-moved-urls.js build", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", "clear": "docusaurus clear", diff --git a/scripts/verify-moved-urls.js b/scripts/verify-moved-urls.js new file mode 100644 index 000000000..89f823848 --- /dev/null +++ b/scripts/verify-moved-urls.js @@ -0,0 +1,102 @@ +// Asserts every docs URL that moved still leads to its page in the built +// site. A moved page's old URL lives on in bookmarks, search results, blog +// posts and other sites' links, so it must keep working for good: a client +// redirect in docusaurus.config.js (plugin-client-redirects) sends it on. +// Docusaurus's own broken-link check cannot see this, because nothing on the +// site links to an old URL any more. +// +// For each move below, the build must hold: +// - a redirect page at the old URL whose target is the new URL, and +// - a real page (not another redirect) at the new URL. +// +// When a page moves, add its old and new URL below in the same change. +// +// Usage: node scripts/verify-moved-urls.js +const fs = require("fs"); +const path = require("path"); + +const BASE_URL = "/docs/"; + +const MOVES = [ + // Into the Universal Mocker section. + { + from: "/running-keploy/mock-quickstart/", + to: "/universal-mocker/mock-quickstart/", + }, + { + from: "/running-keploy/mock-your-tests/", + to: "/universal-mocker/mock-your-tests/", + }, +]; + +// The page plugin-client-redirects writes at an old URL. +const REDIRECT_RE = //; + +const buildDir = process.argv[2]; +if (!buildDir) { + console.error("usage: node scripts/verify-moved-urls.js "); + process.exit(2); +} + +function pageFile(url) { + return path.join(buildDir, url, "index.html"); +} + +function readPage(url) { + try { + return fs.readFileSync(pageFile(url), "utf8"); + } catch (err) { + return null; + } +} + +const failures = []; +for (const {from, to} of MOVES) { + const old = readPage(from); + if (old === null) { + failures.push( + `${from}: no page at the old URL (${pageFile(from)}). Add a redirect ` + + `from it to ${to} in docusaurus.config.js's plugin-client-redirects.` + ); + continue; + } + const m = old.match(REDIRECT_RE); + if (!m) { + failures.push( + `${from}: the old URL holds a page, not a redirect to ${to}. A page ` + + `moved back there? Then remove this move from ${__filename}.` + ); + continue; + } + if (m[1] !== BASE_URL + to.replace(/^\//, "")) { + failures.push( + `${from}: redirects to ${m[1]}, not to ${BASE_URL}${to.replace( + /^\//, + "" + )}. Point its redirect at the page's current URL.` + ); + continue; + } + const target = readPage(to); + if (target === null) { + failures.push( + `${from}: redirects to ${to}, but no page is built there ` + + `(${pageFile(to)}). The page moved again? Point the redirect, and ` + + `this entry, at its current URL.` + ); + continue; + } + if (REDIRECT_RE.test(target)) { + failures.push( + `${from}: redirects to ${to}, which is itself a redirect. Point it at ` + + `the page's current URL, so a reader takes one hop.` + ); + } +} + +if (failures.length > 0) { + console.error(`${failures.length} moved URL(s) no longer lead to a page:`); + for (const f of failures) console.error(`- ${f}`); + process.exit(1); +} +console.log(`All ${MOVES.length} moved URLs redirect to their pages.`); diff --git a/src/components/GetStartedPaths.js b/src/components/GetStartedPaths.js index 881abda4f..8f99705b3 100644 --- a/src/components/GetStartedPaths.js +++ b/src/components/GetStartedPaths.js @@ -1,10 +1,16 @@ import React from "react"; import Link from "@docusaurus/Link"; import useBaseUrl from "@docusaurus/useBaseUrl"; -import {FaRocket, FaMagic, FaRetweet, FaLaptopCode} from "react-icons/fa"; +import { + FaRocket, + FaMagic, + FaRetweet, + FaLaptopCode, + FaLayerGroup, +} from "react-icons/fa"; import {SiKubernetes} from "react-icons/si"; -// The four entry points rendered as cards below, in display order. Exported +// The five entry points rendered as cards below, in display order. Exported // so the docs home can emit them as an ItemList off the same data the links // are built from -- a hand-copied list in the JSON-LD would quietly rot the // first time one of these paths moves. @@ -30,10 +36,21 @@ export const GET_STARTED_PATHS = [ description: "Classic Keploy CLI experience for rapid iteration", href: "/docs/server/installation/", }, + { + name: "Mock the dependencies of the tests you already have", + description: + "Universal Mocker: record your tests' database, queue and API calls once, then replay them offline", + href: "/docs/universal-mocker/overview/", + }, ]; -const [AI_GENERATE, CHROME_EXTENSION, K8S_PROXY, LOCAL_RECORD] = - GET_STARTED_PATHS; +const [ + AI_GENERATE, + CHROME_EXTENSION, + K8S_PROXY, + LOCAL_RECORD, + UNIVERSAL_MOCKER, +] = GET_STARTED_PATHS; export const GetStartedPaths = () => { return ( @@ -47,7 +64,7 @@ export const GetStartedPaths = () => { How do you want to get started?

    - Pick a workflow to begin. You can switch anytime—both paths lead to + Pick a workflow to begin. You can switch anytime—every path leads to reliable, replayable tests.

    @@ -259,6 +276,64 @@ export const GetStartedPaths = () => { + {/* Universal Mocker: spans both columns, below the two cards above */} +
    + {/* Decorative gradient blob */} +
    + +
    +
    + {/* Icon Badge */} +
    + +
    + + {/* Path Label */} +
    + + Universal Mocker + + + Service virtualization + +
    + + {/* Content */} +

    + Run Your Own Tests Without Their Dependencies +

    +

    + Wrap go test, pytest, Jest, JUnit or Playwright with keploy + mock. No mock code to write, and no test to change. +

    +
    + +
    + +
    +
    + +
    +
    +

    + Mock the dependencies of the tests you already have +

    +

    + Record your tests' database, queue and API calls + once, then replay them offline +

    +
    +
    + + → + + +
    +
    +
    ); diff --git a/src/components/Product.js b/src/components/Product.js index 3580610d9..190f8ccc5 100644 --- a/src/components/Product.js +++ b/src/components/Product.js @@ -1,7 +1,6 @@ import React from "react"; import Link from "@docusaurus/Link"; import useBaseUrl from "@docusaurus/useBaseUrl"; -import {FaLayerGroup} from "react-icons/fa"; function UTG() { return ( @@ -233,30 +232,6 @@ function UTG() { -
  • - -
    -
    -
    -
      -
    • -

      - Service virtualization for the tests you already have: - replays their database and API calls offline. -

      -
    • -
    -
    - -
  • ); @@ -269,7 +244,7 @@ export const Products = () => { Products 🛠️

    - Keploy provides four key products that help you streamline your testing + Keploy provides three key products that help you streamline your testing workflow:

    diff --git a/src/pages/index.js b/src/pages/index.js index ec0a438e1..59a216de3 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -48,7 +48,7 @@ export default function Home() { // single author, publication date or headline. DocItem already suppresses // Article on /docs/ for exactly that reason, so emitting one here left the // site's only generic Article on the page the rule was written for. The - // ItemList mirrors the four entry-point cards GetStartedPaths renders. + // ItemList mirrors the five entry points GetStartedPaths renders. const collectionPageSchema = docsUrl ? { "@context": "https://schema.org", diff --git a/versioned_docs/version-4.0.0/keploy-cloud/keploy-console.md b/versioned_docs/version-4.0.0/keploy-cloud/keploy-console.md index 871c72550..f67bcde5f 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/keploy-console.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/keploy-console.md @@ -85,7 +85,7 @@ Similarly, if the test case result is the new expected response, we can normalis - [Install Keploy](/docs/server/installation/) — prerequisite before starting the console. - [Keploy Cloud Application Settings Guide](/docs/keploy-cloud/application-settings/) — add an application to the console. -- [Mock Registry](/docs/universal-mocker/mock-registry/) — manage mocks used during test runs. +- [Mock Registry](/docs/keploy-cloud/mock-registry/) — manage mocks used during test runs. - [Time Freezing](/docs/keploy-cloud/time-freezing/) — stabilize time-sensitive test results. ## Need Help? diff --git a/versioned_docs/version-4.0.0/universal-mocker/mock-registry.md b/versioned_docs/version-4.0.0/keploy-cloud/mock-registry.md similarity index 100% rename from versioned_docs/version-4.0.0/universal-mocker/mock-registry.md rename to versioned_docs/version-4.0.0/keploy-cloud/mock-registry.md diff --git a/versioned_docs/version-4.0.0/keploy-cloud/time-freezing.md b/versioned_docs/version-4.0.0/keploy-cloud/time-freezing.md index 0d8b66b35..25c2768bd 100644 --- a/versioned_docs/version-4.0.0/keploy-cloud/time-freezing.md +++ b/versioned_docs/version-4.0.0/keploy-cloud/time-freezing.md @@ -138,4 +138,4 @@ To build natively instead, download the same `go_freeze_time_` helper, run - [Dynamic Deduplication](/docs/keploy-cloud/deduplication/) — related test-stability feature. - [Static Deduplication](/docs/keploy-cloud/static-deduplication/) — dedupe recorded tests. -- [Mock Registry](/docs/universal-mocker/mock-registry/) — manage the mocks time-freezing relies on. +- [Mock Registry](/docs/keploy-cloud/mock-registry/) — manage the mocks time-freezing relies on. diff --git a/versioned_docs/version-4.0.0/universal-mocker/mock-quickstart.md b/versioned_docs/version-4.0.0/universal-mocker/mock-quickstart.md index 4e29e4be6..56ade8606 100644 --- a/versioned_docs/version-4.0.0/universal-mocker/mock-quickstart.md +++ b/versioned_docs/version-4.0.0/universal-mocker/mock-quickstart.md @@ -30,10 +30,10 @@ command shows the **real output** you should see — nothing is faked. keploy --version ``` -- **Linux** (root, for eBPF), **Windows x86-64**, or **macOS (Apple Silicon)**. - Windows and macOS intercept in userspace, so neither needs Administrator or - `sudo`. Keploy doesn't support Intel Macs. On Windows on ARM, use WSL. Running your tests through a docker command - ([shown at the end](#running-your-tests-in-docker)) works on all three. +- **Linux** (root, for eBPF) or **macOS (Apple Silicon)**. macOS intercepts + in userspace, so it doesn't need `sudo`. Keploy doesn't support Intel Macs. + Native Windows support is coming. Running your tests through a docker command + ([shown at the end](#running-your-tests-in-docker)) works on both. - Python 3. On macOS, use a Homebrew or uv Python (or a virtualenv built on one), not Apple's `/usr/bin/python3`, which macOS won't let Keploy instrument. (`go test` / `npm test` work identically — only the test command changes. On @@ -113,9 +113,13 @@ Your tests pass against the live API — that's the state you want to capture. In another terminal, run your test command under `keploy mock record`: ```bash -keploy mock record -c "python3 -m pytest -q" +keploy mock record --local -c "python3 -m pytest -q" ``` +`--local` keeps the recording in your repository, so you don't need a Keploy +account for this walkthrough. Without `--local`, Keploy asks you to sign in +first (`keploy login`). + ``` 🐰 Keploy: INFO Recording mocks for your test command {"mock-set": "billing", "command": "python3 -m pytest -q"} 🐰 Keploy: INFO Successfully cleared old mocks for refresh. {"testSet": "billing"} @@ -155,7 +159,7 @@ Commit `keploy/` to your repo like a VCR cassette. Re-recording the same set under `keploy mock replay`: ```bash -keploy mock replay -c "python3 -m pytest -q" +keploy mock replay --local -c "python3 -m pytest -q" ``` ``` @@ -190,7 +194,7 @@ served from mocks; the new `/plans/pro` call goes to the real API **and is appended** to the set: ```bash -keploy mock replay -c "python3 -m pytest -q" --on-miss record +keploy mock replay --local -c "python3 -m pytest -q" --on-miss record ``` ``` @@ -232,16 +236,16 @@ echo $? # -> 1 ## Running your tests in Docker The sample's dependency is plain HTTP, so every step above runs natively on -Linux, Windows x86-64 and macOS (Apple Silicon). Natively on macOS and Windows, -Keploy understands HTTP/HTTPS, MySQL and MongoDB calls, and on macOS gRPC calls -too; calls to other services — PostgreSQL, Redis, Kafka, gRPC on Windows and the -like — are captured only as raw bytes and usually don't replay. If your tests +Linux and macOS (Apple Silicon). Natively on macOS, Keploy understands +HTTP/HTTPS, gRPC, PostgreSQL, MySQL, MongoDB, Amazon DynamoDB and Aerospike +calls; calls to other services — Redis, Kafka and the like — are captured only +as raw bytes and usually don't replay. If your tests depend on one of those, run them through a container and point Keploy at that command: ```bash -keploy mock record -c "docker compose run --rm tests" -keploy mock replay -c "docker compose run --rm tests" +keploy mock record --local -c "docker compose run --rm tests" +keploy mock replay --local -c "docker compose run --rm tests" ``` ## Next diff --git a/versioned_docs/version-4.0.0/universal-mocker/mock-your-tests.md b/versioned_docs/version-4.0.0/universal-mocker/mock-your-tests.md index 803f483bd..353cbc516 100644 --- a/versioned_docs/version-4.0.0/universal-mocker/mock-your-tests.md +++ b/versioned_docs/version-4.0.0/universal-mocker/mock-your-tests.md @@ -102,8 +102,7 @@ with no real dependency behind it. - **Linux, or macOS on Apple silicon.** On Linux, Keploy's agent runs as root, so Keploy starts it with `sudo` unless you run Keploy as root. Where nobody can type a password, such as a CI runner, that `sudo` must work without one, as it - does on GitHub-hosted runners. macOS needs no `sudo`. On Windows, - `KEPLOY_PROVEN=1` doesn't run yet: run the commands above without it. + does on GitHub-hosted runners. macOS needs no `sudo`. Native Windows support is coming. - **A test command Keploy runs directly.** In this release, Keploy refuses a Docker command or `--from-container` under the switch, and says so. - **The integration for your test framework.** Each test tells Keploy where it @@ -514,19 +513,21 @@ test.afterEach(({}, testInfo) => post("/agent/scope/end", testInfo.title)); | Platform | How to run | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | **Linux** | Native — `keploy mock record -c "pytest"` (uses eBPF; needs root). | -| **Windows** (x86-64) | Native — same command, without `KEPLOY_PROVEN=1`. Userspace interception, so no Administrator. | +| **Windows** | Coming soon. | | **macOS** (Apple Silicon) | Native — same command. Userspace interception, so no `sudo`. Without `KEPLOY_PROVEN=1`, `-c "docker compose run tests"` also works. | -Natively on macOS and Windows, Keploy understands HTTP/HTTPS, MySQL and MongoDB -calls, and on macOS gRPC calls too; calls to other services — PostgreSQL, Redis, -Kafka, gRPC on Windows and the like — are captured only as raw bytes and usually +Natively on macOS, Keploy 3.9.3 understands HTTP/HTTPS (HTTP/2 included), gRPC, +PostgreSQL, MySQL, MongoDB, Amazon DynamoDB and Aerospike calls; calls to other +services — Redis, Kafka and the like — are captured only as raw bytes and usually don't replay. If your tests depend on one of those, run them in a container (as -above) or on Linux/WSL. On macOS, also +above) or on Linux. The +[dependency table](./overview.md#check-what-it-supports) lists each one. On +macOS, also start the test runner itself rather than through a launcher such as `npm test` or a wrapper script, and use a Homebrew or uv Python (or a virtualenv built on one), not Apple's `/usr/bin/python3` — see [running natively on macOS](/docs/installation/macos-installation/#option-1-run-keploy-natively). -Keploy doesn't support Intel Macs. On Windows on ARM, use WSL. +Keploy doesn't support Intel Macs. ## Refresh in CI diff --git a/versioned_docs/version-4.0.0/universal-mocker/overview.md b/versioned_docs/version-4.0.0/universal-mocker/overview.md index 9b43d4aac..0c19ef17f 100644 --- a/versioned_docs/version-4.0.0/universal-mocker/overview.md +++ b/versioned_docs/version-4.0.0/universal-mocker/overview.md @@ -47,10 +47,18 @@ decides which tests pass. it keeps the recording. A test that doesn't replay is set aside, with the reason and the next step. See [Prove each test offline](./mock-your-tests.md#proven). -4. **Share.** In that mode, the recordings go to Keploy Cloud, under a Keploy - branch named after your git branch. Your repository holds only `keploy.yml` - and `keploy.lock`, which pins each test to its recordings. CI replays what - `keploy.lock` pins. +4. **Share.** In that mode, when you are signed in, the recordings go to Keploy + Cloud, under a Keploy branch named after your git branch. Two things must be + true: + + - `keploy.yml` names a Keploy app (`mock.appId`). Run `keploy app create` + first, or record once with `--app `. + - You record on a git branch other than main. Keploy never publishes to + main: switch to a branch first (`git switch -c `), or pass + `--branch `. + + Your repository holds only `keploy.yml` and `keploy.lock`, which pins each + test to its recordings. CI replays what `keploy.lock` pins. ## Choose the right Keploy product @@ -85,7 +93,7 @@ and ends: | Linux | Yes | Yes | Keploy's agent runs as root; Keploy starts it with sudo. | | macOS (Apple silicon) | Yes | Yes | No sudo or admin rights needed. | | Docker | Yes | Not yet | Pass a `docker run` or `docker compose` command. | -| Windows (x86-64) | Yes | Coming soon | The VS Code flow on Windows is coming soon too. | +| Windows | Coming soon | Coming soon | Native Windows support, VS Code included, is coming. | **Dependencies** in Keploy 3.9.3. "Docker" means: run the tests through a Docker command so Keploy reads the calls on Linux. @@ -119,11 +127,9 @@ coding agent. Then you record, replay and review from the editor. - [Go quickstart](./quickstarts/go.md): run `go test` without PostgreSQL or an HTTP API, then check each test on its own. -- [Mock your tests in 2 minutes](./mock-quickstart.md): a copy-paste walkthrough - with a Python sample app. +- [Mock your tests in 2 minutes](./mock-quickstart.md): a walkthrough with a + Python sample app. - [Mock your own tests](./mock-your-tests.md): every option, per-test checks, CI, and sharing with your team. -- [Mock Registry](./mock-registry.md): keep mocks in Keploy Cloud instead of - your repository. - [CLI commands](/docs/running-keploy/cli-commands/): the full `keploy` command list. diff --git a/versioned_docs/version-4.0.0/universal-mocker/quickstarts/go.md b/versioned_docs/version-4.0.0/universal-mocker/quickstarts/go.md index d31639724..98c023fce 100644 --- a/versioned_docs/version-4.0.0/universal-mocker/quickstarts/go.md +++ b/versioned_docs/version-4.0.0/universal-mocker/quickstarts/go.md @@ -32,8 +32,8 @@ log lines are trimmed and timestamps are removed. You need: -- Linux, or macOS on Apple silicon. On Linux, Keploy's agent runs as root, so - Keploy may ask for your `sudo` password. +- Linux. Keploy's agent runs as root, so Keploy may ask for your `sudo` + password. - [Go](https://go.dev/dl/) 1.21 or newer. - [Docker](https://docs.docker.com/get-docker/), to run PostgreSQL. - Keploy. To install it, run: @@ -46,10 +46,11 @@ You need: ## Step 1: Create the sample package -1. Create a folder and a Go module: +1. Create a folder, a git repository and a Go module: ```bash mkdir orders && cd orders + git init go mod init example.com/orders ``` @@ -210,6 +211,13 @@ You need: docker run -d --name orders-db -e POSTGRES_PASSWORD=postgres -p 5432:5432 postgres:16 ``` + Then wait until it accepts connections. The first start takes a few + seconds: + + ```bash + until docker exec orders-db pg_isready -q -h 127.0.0.1 -U postgres; do sleep 1; done + ``` + 2. In a second terminal, in the `orders` folder, start the rates API: ```bash @@ -251,12 +259,15 @@ ok example.com/orders 0.035s account for this quickstart. Without `--local`, Keploy asks you to sign in first. -Keploy wrote two things: +Keploy wrote four files: - `keploy.yml`, the project's Keploy settings. It holds the app name and the test command. - `keploy/default/mocks.yaml`, the recording: 10 mocks, 8 for PostgreSQL (the connections and each statement) and 2 HTTP calls, each with its answer. +- `keploy/default/last-record.yaml`, the command Keploy recorded this set with. + `keploy mock status` replays the recording with it. +- `keploy/.gitignore`, which keeps Keploy's temporary files out of git. Here is one HTTP call from `mocks.yaml`, trimmed: @@ -437,7 +448,9 @@ reports a result per test. ``` `-p 1` runs one test binary at a time, which per-test checks need in this - release. `-json` shows each test's result, and the reason for a skip. + release. `-json` shows each test's result, and the reason for a skip. It + also makes `go test` print a JSON line for each test event, so the + outputs below leave those lines out and show Keploy's own. `local: true` keeps the recording in the repository, as `--local` did. 4. Start the dependencies again, as in Step 2. Then delete the old recording, @@ -526,20 +539,20 @@ git status --short ``` ``` -?? cmd/rates/main.go +?? cmd/ ?? go.mod ?? go.sum ?? keploy.yml -?? keploy/.gitignore -?? keploy/default/README.md -?? keploy/default/last-record.yaml -?? keploy/default/mappings.yaml -?? keploy/default/mocks.yaml -?? keploy/default/verdicts.yaml +?? keploy/ ?? orders.go ?? orders_test.go ``` +`keploy/default/` holds the recording (`mocks.yaml`), which recorded calls +belong to each test (`mappings.yaml`), each test's result from the judging +rounds (`verdicts.yaml`), the record command (`last-record.yaml`) and a +`README.md`. Commit them all. + Keploy also writes `.keploy-run/`, with the logs of each run. Its own `.gitignore` keeps it out of git. @@ -548,9 +561,8 @@ PostgreSQL and no rates API, and CI can too. ## Clean up -```bash -docker rm -f orders-db -``` +Step 6 stopped PostgreSQL and the rates API, so nothing is left running. +Delete the `orders` folder when you no longer need it. ## Next steps diff --git a/versioned_sidebars/version-4.0.0-sidebars.json b/versioned_sidebars/version-4.0.0-sidebars.json index 9062c2f87..61c13096d 100644 --- a/versioned_sidebars/version-4.0.0-sidebars.json +++ b/versioned_sidebars/version-4.0.0-sidebars.json @@ -71,6 +71,7 @@ "running-keploy/keploy-templatize", "running-keploy/risk-profile-analysis", "keploy-cloud/time-freezing", + "keploy-cloud/mock-registry", "keploy-cloud/keploy-console", "keploy-cloud/auto-test-generation", "keploy-cloud/deduplication", @@ -274,8 +275,7 @@ "collapsed": false, "items": [ "universal-mocker/mock-your-tests", - "running-keploy/utg-vscode-extension", - "universal-mocker/mock-registry" + "running-keploy/utg-vscode-extension" ] } ] From 5f35c95f049d3e2b497ae2f8fa4659d24ede18cd Mon Sep 17 00:00:00 2001 From: slayerjain Date: Fri, 20 Nov 2026 01:24:54 +0530 Subject: [PATCH 4/4] docs: date the mock quickstart's output and name Go's run files - Mock quickstart: its pasted output is from an earlier Keploy release. The page and its description (which llms.txt repeats) now say so, and that the page is being updated for Keploy 3.9.3, instead of calling the output real and the page copy-paste. - Go quickstart, Step 7: the other files in keploy/default/, such as last-replay.yaml, are this machine's run files, and keploy/.gitignore keeps them out of git. Signed-off-by: slayerjain --- .../version-4.0.0/universal-mocker/mock-quickstart.md | 7 ++++--- .../version-4.0.0/universal-mocker/quickstarts/go.md | 4 +++- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/versioned_docs/version-4.0.0/universal-mocker/mock-quickstart.md b/versioned_docs/version-4.0.0/universal-mocker/mock-quickstart.md index 56ade8606..1e37705eb 100644 --- a/versioned_docs/version-4.0.0/universal-mocker/mock-quickstart.md +++ b/versioned_docs/version-4.0.0/universal-mocker/mock-quickstart.md @@ -2,7 +2,7 @@ id: mock-quickstart title: "Get Started: Mock Your Tests in 2 Minutes" sidebar_label: Mock Quickstart -description: A copy-paste walkthrough with a sample app — record the dependency calls its tests make, then replay them offline. Shows the real terminal output at each step. +description: A walkthrough with a sample app — record the dependency calls its tests make, then replay them offline. Its terminal output is from an earlier Keploy release; the page is being updated for Keploy 3.9.3. tags: - mocks - quickstart @@ -19,8 +19,9 @@ keywords: This is a hands-on walkthrough of [`keploy mock`](./mock-your-tests.md) with a small sample app. You'll test an app that calls an external API, record the -API's responses, then run the same tests with the API **switched off**. Every -command shows the **real output** you should see — nothing is faked. +API's responses, then run the same tests with the API **switched off**. The +terminal output on this page is from an earlier Keploy release. Keploy 3.9.3 +prints some lines differently, and this page is being updated for it. ## Prerequisites diff --git a/versioned_docs/version-4.0.0/universal-mocker/quickstarts/go.md b/versioned_docs/version-4.0.0/universal-mocker/quickstarts/go.md index 98c023fce..f1aef3417 100644 --- a/versioned_docs/version-4.0.0/universal-mocker/quickstarts/go.md +++ b/versioned_docs/version-4.0.0/universal-mocker/quickstarts/go.md @@ -551,7 +551,9 @@ git status --short `keploy/default/` holds the recording (`mocks.yaml`), which recorded calls belong to each test (`mappings.yaml`), each test's result from the judging rounds (`verdicts.yaml`), the record command (`last-record.yaml`) and a -`README.md`. Commit them all. +`README.md`. Commit them all. The other files in `keploy/default/`, such as +`last-replay.yaml`, are run files from this machine's last record and replay: +`keploy/.gitignore` keeps them out of git. Keploy also writes `.keploy-run/`, with the logs of each run. Its own `.gitignore` keeps it out of git.