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 a41c744d2..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 @@ -225,6 +229,15 @@ 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/", + }, ], }, ], @@ -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/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/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/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/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/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/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 83% 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 index 4e29e4be6..1e37705eb 100644 --- a/versioned_docs/version-4.0.0/running-keploy/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 @@ -30,10 +31,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 +114,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 +160,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 +195,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 +237,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/running-keploy/mock-your-tests.md b/versioned_docs/version-4.0.0/universal-mocker/mock-your-tests.md similarity index 97% 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 index 803f483bd..353cbc516 100644 --- 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 @@ -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 new file mode 100644 index 000000000..0c19ef17f --- /dev/null +++ b/versioned_docs/version-4.0.0/universal-mocker/overview.md @@ -0,0 +1,135 @@ +--- +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, 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 + +| 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 | 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. + +| 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 + +- [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 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. +- [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 new file mode 100644 index 000000000..f1aef3417 --- /dev/null +++ b/versioned_docs/version-4.0.0/universal-mocker/quickstarts/go.md @@ -0,0 +1,576 @@ +--- +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. 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, a git repository and a Go module: + + ```bash + mkdir orders && cd orders + git init + 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 + ``` + + 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 + 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 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: + +```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. 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, + 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/ +?? go.mod +?? go.sum +?? keploy.yml +?? 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. 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. + +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 + +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 + +- [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 259ce940e..61c13096d 100644 --- a/versioned_sidebars/version-4.0.0-sidebars.json +++ b/versioned_sidebars/version-4.0.0-sidebars.json @@ -68,10 +68,6 @@ "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", @@ -253,6 +249,37 @@ } ] }, + { + "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/quickstarts/go", + "universal-mocker/mock-quickstart" + ] + }, + { + "type": "category", + "label": "Guides", + "collapsible": true, + "collapsed": false, + "items": [ + "universal-mocker/mock-your-tests", + "running-keploy/utg-vscode-extension" + ] + } + ] + }, { "type": "category", "label": "UI Testing",