Using Keploy to Generate API Tests from Real Traffic: A Hands-On Guide

I’ve spent more time fixing broken integration tests than I’d like to admit.

A database seed doesn’t match expectations. A mocked response drifts from reality. A small schema change breaks half the test suite. The API works, but the tests slowly become the most fragile part of the system.

While working on a CRUD-based backend project, I came across Keploy, a tool that takes a very different approach. Instead of writing integration tests by hand, Keploy records real API traffic and turns it into test cases and mocks automatically, without changing application code.

That idea sounded ambitious, so I tried it.

This article is a practical account of that experience how I set Keploy up, how it works internally, the challenges I faced, and what I learned by using it in a real project.

Who This Article Is For

This write-up is intended for:

• backend developers who want to understand Keploy without marketing noise.
• engineers evaluating alternatives to traditional integration testing.

If you’ve built APIs backed by databases and struggled with test maintenance, this will likely feel familiar.

What Is Keploy?

At a high level, Keploy is an open-source API testing tool that generates test cases by recording real requests and responses. You run your application through Keploy, interact with your API normally using curl, Postman, or a frontend, and Keploy captures what happens on the wire.

From that captured traffic, Keploy generates:

• API test cases (requests, responses, headers, status codes)
• mocks for external dependencies like databases or services

Later, you can replay those tests without running the real database or services.

What makes Keploy different from most testing tools is where it operates. It doesn’t sit inside your codebase or require SDKs. Instead, it works at the network and protocol layer, which is why it can mock things like PostgreSQL without SQL mocking libraries.

Project for Keploy Implementation

For this, I integrated Keploy into a simple but realistic backend project: a CRUD API built with FastAPI and backed by PostgreSQL.

Github Repository: https://github.com/caerlower/keploy-demo

Tech stack

• FastAPI for building the API
• PostgreSQL as the database
• SQLAlchemy as the ORM
• Docker for running PostgreSQL
• Keploy for recording and replaying tests

API endpoints

• POST /students/ – create a student
• GET /students/ – fetch all students
• GET /students/{id} – fetch a single student
• PUT /students/{id} – update a student
• DELETE /students/{id} – delete a student

This project was good for Keploy implementation because the API behavior depends heavily on database state, which is exactly where traditional integration tests become painful to maintain.

Installing Keploy on macOS

Keploy supports multiple platforms. I use macOS, the recommended installation uses Lima and Docker.

Installation itself is straight-forward:

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

After installation, you can verify it with:

keploy --version

One important thing to understand early is that Keploy requires elevated privileges on macOS. This is because it intercepts network traffic and DNS resolution. Once you realize Keploy operates below the application layer, this requirement makes sense.

Project Setup — CRUD API Application

Before recording anything, the project needs to be set up correctly so Keploy can actually see the traffic.

1. Navigate to the project directory

git clone https://github.com/Caerlower/keploy-demo.git
cd /workspaces/keploy-demo/fastapi-postgres

2. Create a dedicated Docker network (one-time setup)

Keploy needs to observe traffic between services, so everything must be on the same Docker network.

docker network create keploy-network

If the network already exists, Docker will reuse it.

3. Start the application and database

docker-compose up --build

This starts:

• the PostgreSQL container
• the FastAPI application
• all services attached to keploy-network

4. Install Python dependencies for the project:

pip install -r requirements.txt

At this point, the API should be working normally without Keploy.

Recording API Traffic with Keploy

Once the setup is correct, recording traffic is simple.

keploy record -c "uvicorn application.main:app --reload"

or Using Docker

keploy record -c "docker compose up" --container-name "fastapi-app" --build-delay 50

When Keploy runs in record mode:

• it starts an HTTP proxy
• it intercepts DNS lookups
• your application runs unchanged
• all incoming and outgoing traffic is captured

From your point of view, the app behaves exactly the same as before.

Using the API Normally

Keploy recording the API requests

While Keploy is recording, you use your API normally. For example:

curl -X POST <http://127.0.0.1:8000/students/> \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "Eva White",
    "email": "evawhite@example.com",
    "password": "evawhite111"
  }'

I repeated this for:

• listing students
• fetching a student by ID
• updating records
• deleting records

These were real requests hitting a real PostgreSQL database. Keploy quietly recorded everything in the background. When I stopped the process, test cases and mocks were generated automatically.

Generated Tests and Mocks

After recording, a new keploy/ directory appeared in the project:

It contains:

• test files with full HTTP requests, expected responses, headers, and status codes.
• a mocks.yaml file with recorded PostgreSQL interactions.

At first glance, mocks.yaml looks large and complex. That’s because it stores protocol-level behavior, not simplified SQL mocks. This detail is what allows accurate replay later.

How Keploy Captures Traffic and Generates Tests

Keploy captures traffic in two main ways.

For HTTP requests, it places a proxy between the client and the application. Requests flow from the client to Keploy, then to the app, and back through Keploy before reaching the client. This allows Keploy to capture the complete request–response cycle.

For databases and other external services, Keploy intercepts DNS resolution. When the application tries to connect to PostgreSQL, Keploy detects the protocol and records the communication at the wire level. This includes authentication, queries, transactions, and responses.

Because Keploy records what actually happened, not what the developer assumes will happen, replaying these interactions later is reliable and deterministic.

Running Tests Without PostgreSQL

Keploy testing through recorded Mock data

Replaying the tests is where Keploy really stands out.

keploy test -c "uvicorn application.main:app --reload" --delay 10

or Using Docker

keploy test -c "docker compose up" --container-name "fastapi-app" --build-delay 50  --delay 10

During test replay:

• PostgreSQL does not need to be running
• Keploy blocks real database connections
• recorded mocks are injected instead
• API responses are compared automatically

The --delay 10 flag ensures the application has time to start before tests run.

If replay fails due to missing mocks, it usually means a new database interaction was introduced. In that case, re-recording is the correct fix.

Problems and Challenges I Faced

Most of the challenges I faced were setup-related.

Docker itself wasn’t an issue, but Keploy requires the application and database to share network visibility. When they weren’t on the same Docker network, API requests were recorded but database interactions were missed, leading to incomplete test recordings.

The generated mocks.yaml also looked overwhelming at first, but its detail is intentional. Keploy records protocol-level behavior, which is what makes replay work without a real database.

Overall, these challenges helped me better understand how Keploy and backend systems in general, communicate under the hood.

What I Learned About Keploy Internals

Using Keploy taught me a few important things:

• network-first testing avoids many pitfalls of code-level mocks.
• protocol-level recording is more accurate than mocking SQL or ORM calls.
• real traffic produces better test coverage than assumptions.
• integration tests don’t need live databases to be useful.

More broadly, it changed how I think about testing. Tests don’t have to be a separate phase that comes after development. They can be a byproduct of real usage.

Final Thoughts

Keploy isn’t magic, and it does require some understanding of Docker and networking. But once the setup is correct, the workflow feels natural. You build your API, use it like a real user would, and tests appear automatically.

For beginners, Keploy lowers the barrier to integration testing. For experienced developers, it offers a practical way to reduce test maintenance while increasing confidence in API behavior.

If you build API-heavy systems and spend more time fixing tests than shipping features, Keploy is absolutely worth trying, even if only to rethink how your testing workflow could look.

References

• https://keploy.io/docs/server/installation/
• https://keploy.io/docs/quickstart/quickstart-filter/
• https://keploy.io/docs/running-keploy/api-test-generator/