Keploy: Auto-Generate API Tests from Real Traffic

On a Friday afternoon, you change one line in a payments API: you reorder a single field in the response to match a partner’s new documentation. The unit tests stay green. After deployment, a customer’s old app breaks, the overnight order-sync cron job drifts, and a webhook returns a status the warehouse system does not recognise. Nobody remembers which services that flow passes through. The API has run for three years, its original author has left, and the hand-written tests only cover the paths their authors imagined at the time.

The problem is not a lack of testing discipline. To test a running API, you must rebuild the whole world around it — Postgres, a message queue, partner APIs — and guess what real clients actually send. Meanwhile, real traffic passes through the system every day, carrying edge cases, old clients, and business flows no document records. This article is about using that traffic itself: record it, then replay it as tests.

The Real Problem: A Stable API Nobody Dares to Touch

One Line Changed, One Forgotten Business Flow Broken

A legacy API usually comes with a bloated database, a message queue whose consumers nobody fully knows, and partner integrations whose contracts survive only in old emails. Writing tests by hand means rebuilding every dependency, creating fixtures for every table, faking every message, and hoping you guessed the requests and responses real clients still use.

Hand-written tests also have a built-in blind spot: they only cover the paths their authors thought of. Real traffic contains requests from an old mobile app the team officially stopped supporting but customers still use, a cron job that runs at 2 a.m., a webhook retried after a timeout, and extra fields the server silently accepts. When the suite cannot see those flows, every refactor is a gamble.

Why Plain HTTP Mocking Is Not Enough

An HTTP mock only intercepts outgoing HTTP requests and returns a fixed response. But a real API rarely speaks HTTP alone: it queries Postgres, writes to MongoDB, pushes events to Kafka, waits for a consumer, and only then returns a result. If you mock only HTTP, the rest must still be built for real or mocked piecemeal by hand, and a test passing on a developer machine can still diverge in integration.

What Keploy Is and Which Problem It Solves

Keploy is an open-source platform, licensed Apache-2.0, that creates API, integration, and E2E tests by recording real traffic and replaying it as tests. The project lives at github.com/keploy/keploy, with about 19,346 stars and 2,448 forks, and version v3.6.216 released on 2026-11-03. It records not only API calls but also database queries and streaming events, then replays the whole set as tests with assertions, without changing application code or attaching an SDK.

That approach fits the problem above directly: instead of guessing traffic, you record traffic that already happened and use it as a safety net for the next change. Such tests do not prove code correct against a specification — the end of this article makes that explicit — but they do prove new code still behaves like old code on flows that really ran.

Who Should Use Keploy, and Who Should Wait

Keploy fits backend developers, QA engineers, DevOps/SRE staff, and sysadmins running APIs with database, queue, or external-API dependencies, especially legacy APIs about to be refactored without coverage. Conversely, a new project with no real traffic has nothing to record. An API whose schema changes daily should not lock tests in yet, because every schema change means recording again. Systems that must be proven correct against a specification — computation logic, authorisation, contracts between teams — still need specification-based and contract tests, because replay only compares against the past.

Architecture and How Keploy Works

The Record Flow: Intercepting at the Network Layer, Not in Application Code

Keploy’s interception point sits outside application code. On Linux, it captures network calls with eBPF; on macOS Apple Silicon and Windows x86-64, it uses user-space hooks. With no SDK required, it is language-agnostic: Python, Go, Java, and Node.js applications are recorded the same way, as long as they run under a command Keploy controls.

During recording, Keploy captures requests and responses together with every dependency interaction — Postgres, MySQL, and MongoDB queries, Kafka and RabbitMQ events, and external API responses. The result is two assets: test cases holding input requests and expected responses, and mocks holding the dependency data returned, in the correct order and context.

The Replay Flow: A Mock Server Replaces Every Dependency

When tests run, Keploy restarts the application with exactly the command used during recording, but replaces all dependencies with a mock server. No real database, Kafka, or partner API is needed, so the suite runs offline, on a developer machine or in CI, without a separate dependency cluster for tests.

Two mechanisms keep replay stable. Time freezing fixes the clock during replay, so time-dependent logic does not differ on every run. A diff engine compares the actual response with the recorded response and reports exactly where it diverges, instead of a bare pass or fail. Keploy also expands coverage from recordings combined with an OpenAPI schema, detecting boundary values, missing or extra fields, wrong types, wrong ordering, and retry or timeout cases. In my view, this needs manual QA review, because a schema-generated case can be valid by type yet meaningless for the business.

Coverage reports are split by audience: statement and branch coverage for developers, API schema and business coverage for QA. Shared mocks are managed through a mock registry, so multiple services can use one mock store instead of copying files around.

Technical Limits to Understand Before Using It

The most important limit: Keploy only covers paths that appeared in recorded traffic. An endpoint never called, an error branch never triggered, or an edge case never seen outside production will have no test, because generated cases still need a human to judge their business validity.

The second limit is non-deterministic data: timestamps, UUIDs, random numbers, database sequences, message ordering, and changing external API responses are all sources of flakiness unless denoised. The third is fidelity differences between eBPF on Linux and user-space hooks on macOS and Windows — a test passing on a developer machine may fail in Linux-based CI, so the test environment should be standardised. Finally, specific Linux kernel version and Docker privileged or host-network requirements have not been cross-checked against the official platform-requirements page, so no specific numbers are stated here. Check that page before deploying on Linux or in containers.

The Article’s Only Diagram

flowchart TB
    subgraph Record["RECORD lane — capture real traffic"]
        A1[Client / real traffic] --> A2[Running application]
        A2 --> A3[Keploy interceptor<br/>eBPF on Linux / user-space hook<br/>on macOS, Windows — outside code]
        A3 --> A4a[Record API request/response]
        A3 --> A4b[Record Postgres / MySQL / MongoDB queries,<br/>Kafka / RabbitMQ events, external API responses]
        A4a --> A5[Recording store: Testcases + Mocks]
        A4b --> A5
    end
    subgraph Replay["REPLAY lane — compare with the past"]
        B1[Test Runner] --> B2[Restart application<br/>with the same command]
        B2 --> B3[Mock Server replaces all<br/>DB / queue / external APIs]
        B3 --> B4[Application processes, returns response]
        B4 --> B5[Diff Engine compares actual response<br/>with recorded response — with Time Freeze]
        B5 --> B6[Pass/fail report and coverage]
    end
    A5 -.-> B1

The diagram makes three points: the interception point sits outside application code, mocks replace the whole dependency stack rather than HTTP alone, and replay compares against the past rather than against a specification.

Deploying Keploy: From Installation to Your First Test

Prerequisites and Reference Version

The reference version is v3.6.216, released on 2026-11-03. Supported environments, according to the project’s documentation, are Linux with eBPF, macOS Apple Silicon, and Windows x86-64 with user-space hooks. You need curl to download the installer and a runnable application command, for example python main.py. This section was not tested hands-on; it cross-checks the documentation only. Before recording, follow one rule: record only on staging, or on traffic from which sensitive data has already been stripped.

Installing Keploy

Install with the project’s Quick Start command:

source /dev/stdin <<<"$(curl -fsSL https://keploy.io/install.sh || echo 'echo Keploy installer download failed >&2; return 1')"

An alternative from the project’s homepage, if you want to inspect the installer file before running it:

curl --silent -O -L https://keploy.io/install.sh && source install.sh

Verify the installation with keploy --help. Expected result: the CLI responds and lists the record and test commands.

Recording Real Traffic and Replaying the Suite

Start recording by letting Keploy run your application:

keploy record -c "python main.py"

Replace python main.py with your application’s real start command. While recording runs, generate real traffic through the application: call the main APIs, walk through the important business flows, and include cron jobs or webhooks if possible. When you have enough traffic, stop recording so Keploy generates test cases and mocks.

Replay the suite with:

keploy test -c "python main.py" --delay 10

The --delay 10 flag gives the application time to start before tests begin. Expected result: a report of each test case passing or failing, with a diff when a response diverges from the recording. Once the suite is stable, commit the test cases and mocks to Git so the team shares them and can replay offline, without provisioning a database, queue, or external API. In my view, the first recording should cover one service and one business flow, not the whole system at once.

Keploy in CI/CD and Rollback

Because Keploy runs through a CLI, it fits into GitHub Actions, Jenkins, or Kubernetes without a separate architecture. At first, run it in parallel without blocking the pipeline, to measure real flakiness over many runs. Only when the false-failure rate is low and the team is comfortable reading diffs should it gradually start blocking releases. Shared mocks should go through the mock registry, not be copied between repositories. When the schema changes, record again instead of hand-editing mock files.

Rollback is simple, because Keploy does not change application code: disable its CI step and remove the mocks, and existing hand-written tests are unaffected. Keeping the old suite throughout the parallel-run phase is the safest rollback plan.

Common Errors and How to Handle Them

Failure to capture traffic on Linux is usually related to capture permissions and how the application runs, for example inside a container or virtual machine. Re-check run permissions and the official platform-requirements documentation, rather than guessing requirements the documentation has not confirmed.

Flaky tests usually come from timestamps, random IDs, database sequences, or message ordering. Handle them with Keploy’s denoising and time freezing, and exclude genuinely non-deterministic fields from comparison — but only after confirming a field has no business impact. Stale mocks after a schema change cause mass failures or false passes; re-record for the new schema version and tie mocks to the corresponding commit. A passing test with wrong behaviour is not a tool bug but the nature of replay: it only proves behaviour matches the past, and that past may already contain a bug.

Technical Assessment: Pros, Cons, Security, and Operations

Pros

The biggest advantage is the speed of creating regression tests: no SDK, no code changes, no language dependency, and tests generated from real traffic instead of a test author’s imagination. The second is multi-layer mocking: database, Kafka, Postgres, MongoDB, and external APIs are all replaced by mocks, so tests run offline and test-environment costs drop. The third is regression value: after each change, replay immediately shows which responses diverged from the past, before the change reaches users.

Cons and Hidden Costs

The biggest drawback: tests are locked to past behaviour. If recorded traffic contains a wrong response, dirty data, or outdated logic, Keploy locks that bug in as “correct” and fails when someone fixes it properly. Recorded traffic must therefore be selected and reviewed like code, and every failure must first be classified: is this a new bug, or a correct fix that diverges from the past?

The second hidden cost is mock maintenance: schema changes force re-recording, and the mock store grows with traffic, needing naming, cleanup, and versioning policies. The third is false confidence: a 100% green suite can make a team complacent, while it only covers paths that actually happened. No performance figures are presented here, because no independently verified figures exist.

Security: A Recording Is a Copy of Real Data

Test cases and mocks can contain tokens, personal data, and production data, because they are copies of real traffic. Before committing, review and scrub sensitive data, control access to the repository and CI logs, and scan for secrets. A repository holding mocks should stay private, with a clear policy on who may view recorded files.

System-level packet capture and high-privilege container run modes — if used — also expand the attack surface of the test host. Record only on staging or an isolated CI environment, never production directly without an approval policy and sensitive-data separation.

Operability for DevOps and Sysadmins

For a small team, operating Keploy is light: a standalone CLI, existing CI integration, and no dedicated test-infrastructure cluster. At multi-service scale, the heavy part is mock lifecycle management and replay stability: which mock belongs to which schema version, when to re-record, and who approves diffs on regeneration. In my view, that decides whether Keploy lasts or is abandoned after a few weeks.

Comparing Keploy with Alternatives in the Same Space

Comparison criteria: recording scope, whether code changes or an SDK are needed, offline execution, replay determinism, maintenance cost when the schema changes, and CI/CD integration.

In short: Keploy wins on the speed of regression tests from a running system, and loses on proving correctness against a specification. The two complement each other: use Keploy as a regression net, and keep specification-based and contract tests for behaviour that must be right.

Real-World Use Cases

Business: lock regression for a legacy API before refactoring. Record staging traffic, refactor, then replay to catch divergent responses before release. The team need not rewrite the whole suite before touching old code — the recording is the system’s de facto specification, albeit one of the past.

Homelab and sysadmins: test a self-hosted API without rebuilding the stack. For a self-hosted service with Postgres or Kafka, maintaining a separate dependency cluster just for tests is expensive. Offline replay removes that need, as long as the recording still matches the running service version. When the schema changes, re-record.

DevOps workflow: SDK-free API testing in CI. Keploy is a CLI step that runs in parallel first, then blocks releases once stable. Because it does not change application code, it attaches to an existing pipeline without touching the codebase.

AI and QA workflow: expand coverage from recordings and OpenAPI. QA uses coverage expansion to generate extra edge cases, then reviews each by hand before adding it to the official suite. Generated cases help catch missing fields, wrong types, or wrong ordering, but QA still decides which cases are valid for the business.

Conclusion: Who Should Use Keploy and the Next Step

Keploy fits teams with a running API, complex dependencies, and a need for fast regression tests without rewriting the whole suite from scratch. It does not fit projects with no traffic yet, systems that must be verified against a specification, or environments that forbid recording real data for security reasons. If you are in the first group, the next step is concrete: pick one service and one business flow, record on staging, stabilise replay, and only then expand to blocking CI releases.

For a contrasting view of API testing — one side locking regression, the other hunting vulnerabilities — you can also read Shannon AI pentester for web apps and APIs on this same blog.

Lessons Learned

1. Replay proves sameness, not correctness: a passing test only means behaviour has not changed since the recording, not that the behaviour is right.
2. Test quality equals recorded-traffic quality: recording dirty traffic, or traffic containing a bug or bad data, locks that bug in as the standard.
3. Mocks are assets with a lifecycle: re-record when the schema changes, use clear naming, clean up old mocks, and tie mocks to the corresponding commit.
4. Recorded data is real data: treat test cases and mocks like production data — review, scrub sensitive fields, and control access before committing.
5. Run in parallel before blocking the pipeline: measure real flakiness over many runs before letting Keploy block releases, or CI will quickly lose trust.

Verification Scope

Checked on: 2026-11-04. Verified: the github.com/keploy/keploy repository, the Apache-2.0 licence, star and fork counts, release v3.6.216 dated 2026-11-03, and the install, record, and test commands against official documentation. Platform support and CI integration are vendor documentation, not independently verified. Kernel and Docker privileged/host-network figures came from secondary sources, were not cross-checked against official platform-requirements documentation, and are not stated here. No performance benchmark is presented, because no measured figures exist. AI coverage expansion and coverage reporting are documented behaviour; mock-registry use and release-gate runs are team-chosen configurations. Nothing here was installed or run hands-on.

References

• Keploy on GitHub: https://github.com/keploy/keploy
• Installation guide: https://keploy.io/docs/server/installation/
• How Keploy works: https://keploy.io/docs/keploy-explained/how-keploy-works/
• Keploy CLI commands: https://keploy.io/docs/running-keploy/cli-commands/