How do I test ClickHouse aggregations without seeding data?

Record your application once against a real ClickHouse with Keploy. The query and the aggregate it computed over your real dataset are captured together, so replay asserts on a genuine result with no rows inserted.

Is Keploy a Testcontainers ClickHouse alternative?

For replay, yes. Testcontainers boots a real instance and the test still has to insert enough rows for the aggregate to be meaningful. Keploy records the computed result once and replays it instantly.

Can Keploy handle approximate functions like uniq?

Yes, and it improves on the usual workaround. Because the recorded value is what ClickHouse actually returned for that dataset, replay compares against a real result rather than a pinned guess that shifts as data changes.

Does Keploy work with the native and HTTP interfaces?

Yes. Capture happens at whichever protocol your driver uses, so clickhouse-go over native, clickhouse-connect over HTTP, and the JDBC driver all record and replay the same results.

Is Keploy free to use with ClickHouse?

Yes. The Keploy CLI is open source under Apache 2.0 and free to run on any service with no seat limits. Nothing is installed into the cluster and no configuration change is required.

Keploy as a ClickHouse testing framework

Keploy mocks ClickHouse by recording its protocol beneath your driver, capturing the exact aggregate rows and column types your queries returned, then replaying them during tests. No cluster runs in CI and no table has to be populated to test an aggregation.

Generate ClickHouse tests free

keploy record -c "./analytics-service"

18.4K+

1.2M+300M+mocks createdSlack

What Keploy gives a ClickHouse team

Captured at the ClickHouse protocol

Keploy records the native or HTTP protocol beneath your driver, so an aggregation replays with the rows the server computed and the column types it declared.

Below clickhouse-go, clickhouse-driver, and the JDBC driver
Column types and codecs preserved
Native and HTTP interfaces
Aggregate results captured verbatim

Try Keploy for free Explore the docs

The problem

Why ClickHouse 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 ClickHouse: by hand, with Testcontainers ClickHouse, or with Keploy

A real instance computes the aggregate correctly and needs data inserted to do it. Keploy records the computed result once and replays it with no cluster and no seeding.

By hand

Testcontainers ClickHouse

With Keploy

Select any row for the full comparison, with code.

Get started Book a call

Same coverage, three costs

What you write for ClickHouse 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

analytics_stub.go

hand-written

// Hand-written stub: the query is never parsed or evaluated.

package analytics

type StubStore struct{}

func (StubStore) OrdersByState(day time.Time) ([]Bucket, error) {

// The GROUP BY key, the WHERE clause, and the window are

// all invisible here. This answer is just typed out.

return []Bucket{

{State: "NEW", Count: 4127, TotalMinor: 17_340_400},

{State: "CONFIRMED", Count: 9021, TotalMinor: 38_112_900},

}, nil

}

A wrong GROUP BY key or a missing date filter returns these buckets unchanged, so the query under test is the one thing this cannot verify.

Testcontainers ClickHouse1–2 hours

analytics_test.go

tool-assisted

// Testcontainers ClickHouse: real aggregation, real seeding.

package analytics

func TestOrdersByState(t *testing.T) {

ch := startClickHouse(t)

mustExec(t, ch, createOrdersTable)

// The aggregate is only meaningful with enough rows.

mustInsertRows(t, ch, generateOrders(50_000))

buckets, err := New(ch).OrdersByState(day)

if err != nil {

t.Fatal(err)

}

if len(buckets) != 2 {

t.Fatalf("got %d buckets", len(buckets))

}

Real aggregation semantics — and fifty thousand inserted rows plus a container boot before a single assertion runs.

With Keploy~5 minutes

mocks.yaml

auto-generated

# Recorded with: keploy record -c './your-service'

# The ClickHouse response, captured at the protocol level.

version: api.keploy.io/v1beta1

kind: ClickHouse

name: mock-2

spec:

request:

query: |

SELECT state, count() AS c, sum(amount_minor) AS total

FROM orders WHERE day = ? GROUP BY state

params: ["2026-09-01"]

response:

columns:

- { name: state, type: LowCardinality(String) }

- { name: c, type: UInt64 }

- { name: total, type: UInt64 }

rows:

- { state: "NEW", c: 4127, total: 17340400 }

- { state: "CONFIRMED", c: 9021, total: 38112900 }

The buckets are what ClickHouse computed over the real dataset, so replay asserts on a genuine aggregate without inserting a single row.

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

Explore the docs Request a trial

Keploy vs the alternatives

ClickHouse 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 ClickHouse app once, replay it forever

Keploy sits below your ClickHouse 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 ClickHouse appGET/api/v1/orders/{id}200

RecordingKeploy proxyeBPF · userspace

Goclickhouse-go

Pythonclickhouse-driver and clickhouse-connect

Javathe ClickHouse JDBC driver

Node.js@clickhouse/client

+2 more ClickHouse clients

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

ClickHouse clients Keploy records, driver by driver

Keploy captures ClickHouse at the wire protocol, so 5 of these 6 clients need no adapter, no test double, and no ClickHouse instance in CI.

Auto-mocked
GoView page
clickhouse-go
Auto-mocked
PythonView page
clickhouse-driver and clickhouse-connect
Auto-mocked
JavaView page
the ClickHouse JDBC driver
Auto-mocked
Node.jsView page
@clickhouse/client
Partial
Apache KafkaView page
The Kafka table engine's ingest traffic
Outbound HTTP
Auto-mocked
Outbound HTTP
Any HTTP client call the service makes

Explore the docs Book a call

Quick start

Your first ClickHouse test suite in under five minutes

Every command below runs against your existing ClickHouse 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 "./analytics-service"
3
3Exercise the paths you care about
Run the app against your development ClickHouse. Every query and the aggregate it computed are captured together.
curl 'localhost:8080/analytics/orders-by-state?day=2026-09-01'
curl 'localhost:8080/analytics/revenue?window=7d'
4
4Replay in CI
Replay serves the recorded dependency responses, so the job needs no service containers and no Docker daemon.
keploy test -c "./analytics-service" --delay 8