Skip to content

docs: add Universal Mocker quickstarts and a keploy.yml and lock guide - #990

Merged
slayerjain merged 16 commits into
mainfrom
docs/universal-mocker-2-next
Nov 20, 2026
Merged

slayerjain merged 16 commits into
mainfrom
docs/universal-mocker-2-next

Conversation

@slayerjain

Copy link
Copy Markdown
Member

Why

The Universal Mocker section (#987) had one runnable quickstart, for Go. The Python one showed output from an older release, and nothing covered Node.js, Java, a browser suite, services started by Docker Compose, or which files a project commits.

What changed

  • Quickstarts. Each is a copy-paste sample that records its tests' calls with keploy mock record --local, replays them with the dependencies off, and shows what to commit. No Keploy account is needed.
    • Python (pytest) (/universal-mocker/mock-quickstart/, URL unchanged): rewritten for Keploy 3.9.4. It adds a call with no recording (the 502, the mismatch line and its hint), --on-miss record, and a failing test failing the run. It drops --disableAutoURLDynamic, which the CLI doesn't have, and the Docker and macOS lines no run checked.
    • Node.js (Jest), Java (JUnit, Maven) and Playwright: the same loop for fetch, the JDK's HttpClient, and a web app whose pages Chromium opens.
    • Docker Compose: a pytest suite reads PostgreSQL 16 and keeps a cart in Redis 7, both started by docker compose. It records with the stack up and replays after docker compose down -v.
    • What 3.9.4 does that users will see, as the pages say it:
      • Node.js fetch: a call that --on-miss record adds never ends its answer on a later replay, so the Jest and Playwright pages add calls by recording again.
      • Maven: its own downloads are recorded when they happen during a record, so the Java page runs mvn test once first.
      • Playwright: the webServer's /health check is saved as keploy/default/tests/get-health-N.yaml, which replay doesn't use. The page's .gitignore keeps it out of git. Without certutil, Keploy warns that Chromium's own HTTPS calls are neither recorded nor mocked.
      • A number in a path is treated as an id, so a test for /users/3 gets the answer recorded for /users/1 (Python page).
    • Replaying a clone, and in CI: the replay gives the test command no network, so each page says what a clone installs first: the venv and pip install (Python, Docker Compose), npm ci (Jest), npm ci and npx playwright install --with-deps chromium (Playwright), and go mod download (Go, from docs: add a Universal Mocker section to the navbar and sidebar #987). For Maven, mvn dependency:go-offline isn't enough; a run that starts Surefire but matches no test (mvn -B test -Dtest='*#none' -Dsurefire.failIfNoSpecifiedTests=false) is.
  • Guide: keploy.yml and keploy.lock (/universal-mocker/guides/keploy-yml-and-lock/): what a project commits, the mock: keys most projects set, and how keploy.lock pins one recording per test by sha256 digest. It covers keploy app create, the first record with --lock, the app's recording pin, keploy mock register, and keploy mock publish --from for a recording whose publish failed, with each refusal. It carries docs: add a page for keploy.lock and keploy mock publish #958's page, moved under the new section. In 3.9.4 a --branch replay of a branch that keploy mock register listed has no start-up recording and goes red, so the guide says to replay from the lock.
  • Overview and Mock your tests, macOS: the dependency table and the macOS paragraph now describe Keploy 3.9.4, read from that release's parser registration: Couchbase, Memcached, Apache HBase and Apache ZooKeeper now work natively on macOS, as Aerospike already did. Redis, Kafka, Apache Pulsar and Amazon SQS still need Docker there.
  • Go quickstart: its outputs are now from a Keploy 3.9.4 run, and the keploy mock status block marks the lines it leaves out.
  • Mock your tests: the open-source build passes Redis calls through in record and replay, so Redis must be up for the replay; Keploy Enterprise, which the install script installs, records and mocks Redis, with no account under --local. A test that a begin told to skip sends no end, or one with "outcome": "skipped". This carries the still-true text of docs: say what the end of a skipped test carries under KEPLOY_PROVEN #970 and docs: recording and mocking Redis needs Keploy Enterprise #939.
  • Redirects: the list moves to src/redirects.js. docusaurus.config.js passes it to plugin-client-redirects, and verify-moved-urls reads the same list, so every listed redirect is checked. The check also takes several old URLs in one from, fails on an empty list, and checks that a target's #fragment is on the page, with the fragment escaped.
  • Pages that vanish: build_and_check.yml now also builds the pull request's base commit, and verify-moved-urls checks that every page in that build's sitemap still leads to a page: the page itself, or a redirect to a real page. That is every page in the base build's sitemap; tag pages and the 1.0.0 and 2.0.0 docs are not in it. A page moved or deleted with no redirect fails the job. A closed pull request's run skips the base build and checks the redirects list only.
  • VS Code extension page: the commands read as the extension shows them, with no label in parentheses, and the section says it records for Integration Testing.
  • Navigation: the sidebar lists Python (pytest), Node.js (Jest), Java, Playwright and Docker Compose under Quickstarts, and the guide under Guides. The overview and the quickstarts link to each other.

How it was checked

  • Each quickstart was run end to end on Linux as a non-root user with sudo, with Keploy 3.9.4 from the public installer and every block taken from the page itself, the Go page included. Each output on the page is from those runs, trimmed, with the timings that run printed.
  • Each page's clone step was run as a fresh user with an empty home (no Maven repository, module cache, npm cache, browsers or Keploy), the way a CI runner starts: clone, install Keploy, the page's install step, then the replay, with Keploy 3.9.4. All six replays passed. Without the step, the Go and Java replays failed on DNS misses for proxy.golang.org and repo.maven.apache.org, and so did Java's with only mvn dependency:go-offline.
  • The keploy.yml and keploy.lock guide's commands were run with the released Keploy 3.9.4 against Keploy Cloud, and its keploy.lock and staged-recording examples are from that run. Its --branch replay is still red there, so the guide's note stays.
  • yarn build (onBrokenLinks and onBrokenAnchors: throw) and every verify script, verify-moved-urls included, on Node 22, as CI builds it, then a build of main and verify-moved-urls against its sitemap.
  • prettier@2.8.8 --check on every changed .js and .md file, as CI runs it.
  • Each condition in verify-moved-urls was broken on purpose, 38 ways, and a fixture case caught each one, the sitemap check and the escaped fragment included. A build whose config drops the redirect list fails the check.
  • The workflow's closed-event conditions (the base build's if: and the URL check's branch) were broken 7 ways, and running the two steps as a runner does for opened, synchronize and closed events caught each one.

- Redirects: the list moves to src/redirects.js. docusaurus.config.js
  gives it to plugin-client-redirects, and verify-moved-urls reads the
  same list, so every redirect is checked, not a copy of some of them.
  The check also takes a list of old URLs in one `from`, fails on an
  empty list, and checks a target's #fragment is on the page.
- VS Code extension page: the running-app commands carried a label in
  parentheses that the extension does not show. They now read as the
  extension shows them, and the section says it records for
  Integration Testing.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
The mock guide moved into the Universal Mocker section, so two open
edits to its old path land here instead:
- The open-source keploy neither records nor mocks Redis: it passes
  Redis calls through in mock record and mock replay, so Redis must be
  up for the replay. Keploy Enterprise, which the install script
  installs by default, records and mocks it. The quick start's replay
  comment says the same.
- A test process that a begin told to skip sends no end for that test,
  or one with "outcome": "skipped". An end with another outcome, or
  none, means the test ran, and Keploy refuses it (409 not_open).

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
A new guide says which files a project commits (keploy.yml and
keploy.lock, or keploy/ with mock.local), the mock: keys most projects
set, and how keploy.lock pins one recording per test and one for the
start-up by sha256 digest. It shows how keploy app create saves
mock.appId, how the first record makes the lock with --lock, the app's
recording pin and keploy mock register, and how keploy mock publish
--from publishes a recording that a record kept in .keploy-run/staging/
when its own publish failed, with each refusal.

Every command and output on the page comes from a run of the released
Keploy 3.9.3 against Keploy Cloud. The sidebar lists the guide under
Guides, and the overview and the mock guide link to it.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
The Universal Mocker's 2-minute quickstart showed output from an older
release (a mock set named after the folder, log lines 3.9.3 no longer
prints) and a Docker command that was never run.

Rewrite it as the Python quickstart, in the Go quickstart's shape, from
a run of the released 3.9.3 CLI as a non-root user, with every code
block taken from the page itself:
- record and replay with --local, with the API stopped by Ctrl+C;
- a call with no recording: the 502, the mismatch line and its hint;
- --on-miss record adding the call, then a replay that serves all three;
- a failing test, and Keploy exiting with its exit code;
- what git add stages, with the venv and Python caches in .gitignore.

Keep the note that an id in a path matches the recorded call (a test
for /users/3 got the answer recorded for /users/1), now checked on
3.9.3, and drop --disableAutoURLDynamic, which the CLI doesn't have.
Drop the macOS and Docker claims the run didn't check: the page says
Linux. The sidebar label is now "Python (pytest)"; the URL is unchanged.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
The Universal Mocker had quickstarts for Go and Python only.

Add a Node.js quickstart: a small app that calls a users API with
fetch, and Jest tests for it. Every code block is taken from the page
and run as a non-root user with the released 3.9.3 CLI, Node.js 22 and
Jest 30, with --local and no account:
- record, then replay with the API stopped by Ctrl+C;
- a call with no recording: the 502, the mismatch line and its hint;
- recording again to add the call, then a replay that serves all three;
- a failing test with Jest's expected and received values, and Keploy
  exiting with the test command's exit code;
- what git add stages, with node_modules in .gitignore.

The page adds a new call by recording again, not with --on-miss record:
in 3.9.3, a call that --on-miss record adds from Node.js fetch is saved
without its Content-Length, so later replays never end its answer and
the test times out. A caution on the page says so.

List the page in the sidebar after the Python quickstart, and link it
from the overview and from the Python quickstart.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
The Universal Mocker had quickstarts for Go, Python and Node.js only.

Add a Java quickstart: a small app that calls a users API with the
JDK's HttpClient, and JUnit 5 tests for it, run with mvn test. Every
code block is taken from the page and run as a non-root user with the
released 3.9.3 CLI, Temurin JDK 21 and Maven 3.9, with --local and no
account:
- record, then replay with the API stopped by Ctrl+C;
- a call with no recording: the 502, the mismatch line and its hint;
- recording again to add the call, then a replay that serves all three;
- a failing test with JUnit's expected and actual values, and Keploy
  exiting with the test command's exit code;
- what git add stages, with target/ in .gitignore.

The page explains the two "Picked up JAVA_TOOL_OPTIONS" lines (Keploy's
truststore, one per JVM) and the h2c upgrade headers in the recording.
It runs mvn test once before recording, because Maven's own downloads
are recorded too when they happen during a record: a record with an
empty local Maven repository saved 166 calls where the app makes 3.

List the page in the sidebar after the Node.js quickstart, and link it
from the overview and from the Python and Node.js quickstarts.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
A new Universal Mocker quickstart, "Playwright", after the Java one in
the sidebar, linked from the overview and the Node.js page.

The sample is a small web app on node:http that renders its pages from
a stand-in users API. Playwright's webServer starts it, and Chromium
opens its pages. The page records the app's calls with keploy mock
record --local, replays them with the API off, adds a page whose call
the recording lacks, and shows a failing test failing the run.

Every output is from a run of the page's own blocks, as a non-root user
on Linux, with the released Keploy 3.9.3 and Playwright 1.65.1.

The page also says what that run showed:
- Chromium's requests to the app are not recorded: Keploy passes them to
  the app, and its self-call lines count them.
- The webServer's /health check is saved as a test case,
  keploy/default/tests/get-health-N.yaml, which mock replay doesn't
  use.
- Without certutil, Keploy warns that Chromium's own HTTPS calls are
  neither recorded nor mocked; this sample's calls are HTTP, from the
  app.
- New calls are added by recording again, not --on-miss record, as on
  the Node.js page, because the app calls with fetch.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
Keploy 3.9.3 saves the Playwright webServer's readiness request as
keploy/default/tests/get-health-N.yaml, and mock replay doesn't use
it. The page's .gitignore step now adds
keploy/*/tests/get-health-*.yaml, so git add . skips the file, and the
page says why.

The outputs are from a new run of the page's own blocks, as a non-root
user on Linux, with the released Keploy 3.9.3: git status no longer
lists the file.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
A new Universal Mocker quickstart, "Docker Compose", after the
Playwright one in the sidebar, linked from the overview and the Python
page.

Docker Compose starts PostgreSQL 16 and Redis 7 for a small pytest
suite that reads products with psycopg and keeps a cart with redis-py.
The page records the tests' calls with keploy mock record --local while
the stack is up, stops the stack with docker compose down -v, shows the
tests failing on their own, and replays them under keploy mock replay
--local with no service running. It notes that the open-source build
passes Redis calls through, so with it Redis must be up for the
replay; the install script's Keploy Enterprise records and mocks them.

Every output is from a run of the page's own blocks, as a non-root user
in the docker group on Linux, with the released Keploy 3.9.3 and
Python 3.11. Three more replays of the committed recording passed too.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
The quickstarts said anyone can replay the recording on a clone, and
CI can too. The replay gives the test command no network, so a clone
replays only once the test command's own dependencies are on disk.
Each page now names that step. Every step was run first as a fresh user
with an empty home, as a CI runner starts, with Keploy 3.9.3:

- Python and Docker Compose: the venv and pip install.
- Jest: npm ci. Playwright: npm ci and npx playwright install
  --with-deps chromium.
- Go: go mod download. Without it, go test can't reach
  proxy.golang.org and Keploy reports DNS misses for it.
- Java: mvn -B test -Dtest='*#none'
  -Dsurefire.failIfNoSpecifiedTests=false. Without it, or with only
  mvn dependency:go-offline or -Dtest=none, the replay ends in BUILD
  FAILURE on DNS misses for repo.maven.apache.org.

Also:
- keploy.yml and keploy.lock guide: in 3.9.3, a --branch replay of a
  branch that keploy mock register listed leaves out its start-up
  recording and goes red, so the guide says to replay from the lock.
- Mock your tests: Keploy Enterprise records and replays Redis with
  --local and no account, as the Docker Compose page does.
- The mismatch line's path tag differs on every run, so the pages show
  it as #….

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
verify-moved-urls checked only the redirects src/redirects.js lists,
so a page moved or deleted with no redirect still passed. Given a base
build as a second argument, it now also checks every page in that
build's sitemap: this build must have the page itself, or a redirect
there to a real page.

build_and_check.yml builds the pull request's base commit the same way
(yarn install --frozen-lockfile, then yarn build) and passes that build
to the check.

The URL fragment the check looks for as an id is now escaped before it
goes into a RegExp, so a fragment such as v1.2 no longer matches
id="v1x2".

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
A closed pull request has no change left to protect, so building its
base commit there only costs time. The base build now runs on opened
and synchronize only, and on closed the URL check runs without a base
build, so it checks the redirects list alone.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
Keploy 3.9.4 registers the Couchbase, Memcached, HBase and ZooKeeper
parsers on every OS, so they now work natively on macOS, as Aerospike
already did. Redis, Kafka, Pulsar and SQS are still registered on
Linux only, so on macOS they still need Docker.

The overview's dependency table and the macOS paragraph in Mock your
tests now name 3.9.4 and list each one that way.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
Every quickstart was run again as written with Keploy 3.9.4 from the
public installer. Only timings changed, and the Docker Compose page's
"docker compose ps" table, so those lines now come from the 3.9.4 run
and each page names 3.9.4.

On 3.9.4, a call that --on-miss record adds from Node.js fetch still
times out on the next replay, and a --branch replay of a registered
branch still goes red, so both notes stay and name 3.9.4.

The Go page's keploy mock status block now marks the lines it leaves
out, and the Python page's trimmed on-miss line keeps the log's spacing.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
The keploy.lock example and the staged-recording example in the
keploy.yml and keploy.lock guide now come from a Keploy 3.9.4 run of
the guide's own steps, with keploy.yml committed before the record as
the guide says. Each digest's comment now names 3.9.4 and that commit.

A replay with --branch alone is still red on 3.9.4, so its note stays.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
mock-your-tests.md listed Amazon SQS with the services a native macOS
record keeps only as raw bytes. On macOS, Keploy 3.9.4 records SQS calls
as readable HTTPS calls, but without the SQS matching it has on Linux, so
some of them miss on replay. Say that, and that SQS tests still need
Linux or Docker, as the overview's table says. Redis, Kafka and Apache
Pulsar stay under raw bytes.

Signed-off-by: slayerjain <shubhamkjain@outlook.com>
@slayerjain
slayerjain force-pushed the docs/universal-mocker-2-next branch from a89ad0c to 9d54f68 Compare November 20, 2026 14:53
@slayerjain
slayerjain merged commit a18974e into main Nov 20, 2026
6 checks passed
@slayerjain
slayerjain deleted the docs/universal-mocker-2-next branch November 20, 2026 15:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant