Do I need TimescaleDB running to replay?

No. The recorded responses are served from the test set, so a replay run needs no TimescaleDB instance at all. You need it once, during the recording pass.

Is my Postgres driver still exercised?

Yes. Keploy replays at the protocol, so the client parses, converts and decodes exactly as it does in production. That is the difference from a stubbed client, which skips all of it.

How do I refresh the recordings?

Record again. One command re-captures every TimescaleDB interaction, so a schema or response change surfaces as a diff instead of a stale fixture that still passes.

Does it understand hypertables?

It does not need to. Capture is at the wire, so whatever Timescale returns for a hypertable or an aggregate query is what replays, without Keploy modelling the extension.

Does Keploy replace Testcontainers?

Not where you need the real engine, and that is worth being clear about. Use Testcontainers when a test genuinely has to exercise TimescaleDB itself. Keploy covers the much larger set of tests that only need the responses.

Keploy as a TimescaleDB testing framework

Keploy records the Postgres wire protocol exchanges your service has with TimescaleDB, then replays them byte for byte in tests. Your Postgres driver runs unchanged and does its real work on every run, but CI needs no TimescaleDB instance, no schema and no seed data.

Generate TimescaleDB tests free

keploy record -c "<your app start command>"

18.5K+

1.2M+300M+mocks createdSlack

What Keploy gives a TimescaleDB team

Every TimescaleDB call your service makes

Keploy records hypertable queries at the Postgres protocol, including continuous aggregates, so a test replays the rows Timescale returned rather than rows you inserted by hand.

Hypertable queries captured
Continuous aggregates included
Any Postgres driver
No extension to install in CI

Try Keploy for free Explore the docs

The problem

Why TimescaleDB integration tests slow teams down

The friction is rarely the assertions. It is everything around them — spinning up dependencies, keeping mocks honest, and repairing tests after every refactor.

Book a call Explore the docs

Three ways to do it

Testing TimescaleDB: by hand, with Testcontainers, or with Keploy

Testcontainers gives a test a real TimescaleDB at the cost of running one. A stubbed client is cheap but skips the driver. Keploy replays the real protocol with nothing running.

By hand

Testcontainers

With Keploy

Select any row for the full comparison, with code.

Get started Book a call

Same coverage, three costs

What you write for TimescaleDB vs what Keploy records

All three produce the same assertion. Only the third still passes after the next refactor without anyone editing it.

By hand2–4 hours

order_repository_test.py

hand-written

from unittest.mock import MagicMock

# A stub TimescaleDB client: every reply is typed out here.

def test_reads_an_order():

client = MagicMock()

client.fetch.return_value = {

"id": "o-1",

"total": 4200,

"status": "NEW",

}

order = OrderRepository(client).find("o-1")

assert order.total == 4200

# Nothing here exercised the driver, so a type or encoding

# change in the real reply cannot fail this test.

A hand-written stub of the TimescaleDB client. The driver never runs.

Testcontainers1–2 hours

order_repository_container_test.py

tool-assisted

import pytest

from testcontainers.core.container import DockerContainer

@pytest.fixture(scope="session")

def client():

# Boots a real TimescaleDB per suite. Needs a Docker daemon

# available wherever the tests run, including CI.

with DockerContainer("timescaledb:latest") as c:

c.start()

yield connect(c.get_container_host_ip(), c.get_exposed_port(0))

def test_reads_an_order(client):

# Schema and seed data are still written by hand.

seed(client, id="o-1", total=4200, status="NEW")

order = OrderRepository(client).find("o-1")

assert order.total == 4200

Testcontainers runs the real TimescaleDB. Fidelity is genuine; the job pays for it.

With Keploy~5 minutes

keploy/test-set-0/test-1.yaml

auto-generated

version: api.keploy.io/v1beta1

kind: Http

name: test-1

spec:

req:

method: POST

url: /orders/o-1/confirm

resp:

status_code: 200

body: '{"id":"o-1","status":"CONFIRMED","total":4200}'

assertions:

noise:

- body.confirmedAt

---

kind: Postgres

spec:

query: select id, total, status from orders where id = $1

rows:

- { id: "o-1", total: 4200, status: "NEW" }

---

kind: Http

spec:

request:

url: https://api.payments.example.com/v1/payment_intents/tok_123/confirm

response:

body: '{"status":"AUTHORIZED"}'

Recorded from one real request. Nothing here was typed by hand.

Times are estimates for authoring one endpoint’s coverage from scratch, not measurements.

Explore the docs Request a trial

Keploy vs the alternatives

TimescaleDB testing tools, compared

The options a team on relational databases actually reaches for, and where each one genuinely wins. Select a row for the full comparison.

Keploy

Testcontainers

H2

DBUnit

pg-mem

Postman

SmartBear ReadyAPI

Best in classStrongPartialNot covered

Assessments reflect each tool’s documented behaviour, not benchmark measurements.

Request a trial Book a call

How it works

Record your TimescaleDB app once, replay it forever

Keploy sits below your TimescaleDB process at the network layer. It watches the calls your app already makes, then serves them back on replay so tests run with no dependencies attached.

Your TimescaleDB appGET/api/v1/orders/{id}200

RecordingKeploy proxyeBPF · userspace

PostgreSQLPostgres protocol beneath the driver

MySQLMySQL protocol beneath the driver

Outbound HTTPEvery outbound HTTP call

RedisRESP beneath the cache client

+2 more TimescaleDB dependencies

An example shape of a captured call. Your own endpoints and dependencies come from your real traffic, so nothing here has to be written by hand.

Try Keploy for free Request a trial

Mock coverage

What Keploy mocks for TimescaleDB, with zero config

6 of the 6 dependencies a typical TimescaleDB service talks to are stubbed from the recording itself — no mock classes, no fixture files, no containers in CI.

Auto-mocked
PostgreSQLView page
Postgres protocol beneath the driver
Auto-mocked
MySQLView page
MySQL protocol beneath the driver
Outbound HTTP
Auto-mocked
Outbound HTTP
Every outbound HTTP call
Auto-mocked
RedisView page
RESP beneath the cache client
Auto-mocked
MongoDBView page
Wire protocol beneath the Mongo driver
Auto-mocked
Apache KafkaView page
Kafka protocol beneath the client

Explore the docs Book a call

Quick start

Your first TimescaleDB test suite in under five minutes

Every command below runs against your existing TimescaleDB service. Nothing in your source tree changes.

1
1Install the Keploy CLI
A single binary. It needs a Linux kernel with eBPF support, or Docker on macOS and Windows — and it adds nothing to your project's dependencies.
curl -sSL https://keploy.io/install.sh | bash
2
2Record your service
Pass the command you already use to start the app. Keploy runs it and watches every socket it opens.
keploy record -c "<your app start command>"
3
3Exercise the paths you care about
Use curl, your frontend, or an existing smoke script. Every request becomes a test case with its TimescaleDB calls captured alongside it.
curl -X POST localhost:8080/orders/o-1/confirm
curl localhost:8080/orders/o-1
4
4Replay in CI
Replay serves the recorded dependency responses, so the job needs no service containers and no Docker daemon.
keploy test -c "<your app start command>" --delay 10