How do I mock Cassandra queries in tests?

Record your application once against a real cluster with Keploy. It captures each CQL statement, its consistency level, and the rows the coordinator returned, then answers the same queries from that recording.

Is Keploy an embedded Cassandra alternative?

For replay, yes. An embedded or containerised Cassandra is among the slowest test dependencies to start. Keploy records a real cluster once and replays its responses with none of that startup cost.

Does Keploy capture the CQL consistency level?

Yes. The consistency level travels with the query in the binary protocol, so it is recorded and replayed — meaning a read that only succeeds at ONE cannot silently pass as a QUORUM read.

Can Keploy replay Cassandra result paging?

Yes. The opaque paging state is part of the recorded response, so a paged read replays page by page exactly as the cluster returned it rather than as a flat list.

Does Keploy work with ScyllaDB?

Yes. ScyllaDB implements the CQL binary protocol, so capture and replay are identical — the recorded exchanges are protocol messages either way.

Is Keploy free to use with Cassandra?

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 Cassandra testing framework

Keploy mocks Cassandra by recording the CQL binary protocol beneath your driver, capturing the rows, column metadata, and paging state the cluster returned, then replaying them during tests. No cluster runs in CI and no keyspace has to be created.

Generate Cassandra tests free

keploy record -c "java -jar orders.jar"

18.4K+

1.2M+300M+mocks createdSlack

What Keploy gives a Cassandra team

Captured at the CQL binary protocol

Keploy records the protocol beneath your driver, so a query replays with the rows the coordinator returned, the column metadata it described, and the paging state for the next page.

Below the Java, Python, Node, and Go drivers
Column metadata and CQL types preserved
Prepared statement ids captured
Paging state replayed

Try Keploy for free Explore the docs

The problem

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

A real cluster validates CQL properly and is among the slowest dependencies to start. Keploy records those responses once and replays them with no cluster at all.

By hand

Testcontainers Cassandra

With Keploy

Select any row for the full comparison, with code.

Get started Book a call

Same coverage, three costs

What you write for Cassandra 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_dao_stub.py

hand-written

# Hand-written stub: CQL restrictions are never checked.

class StubOrderDao:

def __init__(self):

self._rows = {

"ord_1": {"id": "ord_1", "amount_minor": 4200, "state": "NEW"},

}

def by_id(self, order_id):

return self._rows.get(order_id)

def by_state(self, state):

# Cassandra would reject this without a partition key

# or ALLOW FILTERING. Nothing here does.

return [r for r in self._rows.values() if r["state"] == state]

The by_state query would be rejected by a real cluster without ALLOW FILTERING. Here it returns rows and passes.

Testcontainers Cassandra1–2 hours

test_order_dao.py

tool-assisted

# Testcontainers Cassandra: a real cluster per suite.

import pytest

from cassandra.cluster import Cluster

from testcontainers.cassandra import CassandraContainer

@pytest.fixture(scope="session")

def session():

with CassandraContainer("cassandra:5.0") as c:

cluster = Cluster(c.get_contact_points())

s = cluster.connect()

s.execute(CREATE_KEYSPACE)

s.execute(CREATE_TABLE)

yield s

def test_reads_an_order(session):

session.execute(INSERT_ORDER, ("ord_1", 4200, "NEW"))

order = OrderDao(session).by_id("ord_1")

assert order.amount_minor == 4200

Real CQL validation — and the cluster start plus keyspace creation is one of the slowest fixtures in any test suite.

With Keploy~5 minutes

mocks.yaml

auto-generated

# Recorded with: keploy record -c 'java -jar orders.jar'

# The Cassandra response, captured at the CQL binary protocol.

version: api.keploy.io/v1beta1

kind: CQL

name: mock-3

spec:

request:

query: "SELECT id, amount_minor, state FROM orders WHERE id = ?"

params:

- "ord_1"

consistency: QUORUM

response:

column_metadata:

- name: id

type: TEXT

- name: amount_minor

type: BIGINT

- name: state

type: TEXT

rows:

- id: "ord_1"

amount_minor: 4200

state: "NEW"

paging_state: null

The consistency level and paging state are recorded with the query, so a read that only works at ONE cannot silently pass as a QUORUM read.

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

Explore the docs Request a trial

Keploy vs the alternatives

Cassandra testing tools, compared

The options a team on document and wide-column stores actually reaches for, and where each one genuinely wins. Select a row for the full comparison.

Keploy

Testcontainers

mongodb-memory-server

mongomock

Fongo

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

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

RecordingKeploy proxyeBPF · userspace

Javathe DataStax Java driver and Spring Data Cassandra

Pythoncassandra-driver

Node.jscassandra-driver

Gogocql

+2 more Cassandra 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

Cassandra clients Keploy records, driver by driver

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

Auto-mocked
JavaView page
the DataStax Java driver and Spring Data Cassandra
Auto-mocked
PythonView page
cassandra-driver
Auto-mocked
Node.jsView page
cassandra-driver
Auto-mocked
GoView page
gocql
Auto-mocked
ScyllaDB
CQL-compatible, so capture is identical
Partial
.NETView page
CassandraCSharpDriver

Explore the docs Book a call

Quick start

Your first Cassandra test suite in under five minutes

Every command below runs against your existing Cassandra 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 "java -jar orders.jar"
3
3Exercise the paths you care about
Run the app against your development cluster. Every CQL statement, its consistency level, and the rows returned are captured together.
curl localhost:8080/orders/ord_1
curl 'localhost:8080/orders?partition=2026-09'
4
4Replay in CI
Replay serves the recorded dependency responses, so the job needs no service containers and no Docker daemon.
keploy test -c "java -jar orders.jar" --delay 15