CassandraUnit documentation¶
Test fixtures and assertions for Apache Cassandra, with an embedded server if you want one.
CassandraUnit is three things, and you can take any of them.
The dataset loader turns a YAML, JSON, XML, CSV or CQL file — or a builder, in Java — into rows
in a real keyspace, with every value converted using the column's actual type read from the live
schema — so a text column holding "1" stays the string "1", and uuid, timestamp, blob,
collections and UDTs all work without you hand-formatting CQL literals. It runs against any
CqlSession you hand it.
The assertions run the comparison the other way: given a table, is it what it should be? Either as a file listing every row, or as fluent code checking one value. Both read the column's real type from the live schema, exactly as the loader does, so the two directions agree about what a value is.
The embedded server starts a real Apache Cassandra node inside your test JVM, for when you want one and would rather not run Docker. That in-process design is the source of both its convenience and its constraints: exactly one Cassandra per JVM, your test JVM needs the JVM flags a Cassandra server needs, and your JDK is the server's JDK.
The loader does not need the server. If you are already using Testcontainers' Cassandra
module, it gives you the node and
cassandra-unit-dataset gives you the data — withInitScript is one CQL file and nothing else.
What to declare¶
Each artifact contains the one above it, so declare only the lowest line you need. All are group
org.cassandraunit, version 5.2.0, scope test.
| What you want | Declare |
|---|---|
| The dataset loader and the assertions | cassandra-unit-dataset |
| …and an embedded Cassandra | cassandra-unit |
| …and Spring's TestContext integration | cassandra-unit-spring |
A few dependencies are deliberately optional, so they never arrive on their own and you declare
them yourself: assertj-core for the fluent assertions
(details), jackson-dataformat-csv for .csv datasets
(details), and spring-test + spring-context for SpringSessions, which loads
fixtures through a Spring-managed CqlSession (details).
Start here¶
Pick the one that matches what you already have:
| I already have a Cassandra — Testcontainers, a local node, ScyllaDB, Astra | Your first test — your own Cassandra — the cassandra-unit-dataset artifact. No embedded server, no JVM flags, no JDK ceiling. |
| I want one started for me, in-process | Your first test — embedded server — the cassandra-unit artifact. Step 2 is not optional: an embedded Cassandra 5.0 needs JPMS flags on the test JVM, and without them the node fails to start. |
Either way, Datasets is the page you will come back to — it applies to both artifacts. And asserting is the part nothing else in the Java/Cassandra ecosystem does: stating what a table should hold after a test, not only what it held before, either in code for a single value or row count or with a dataset file for every row.
Reference¶
| Datasets | The two dataset kinds: .cql scripts and row datasets in YAML/JSON/XML/CSV or built in Java, how values are converted from the live schema, and keyspace creation and deletion between tests. |
| Asserting in code | The fluent CqlAssertions API: navigating session to keyspace to table to row, the method reference, and the optional AssertJ dependency. |
| Asserting with a dataset file | @ExpectedCassandraDataSet: comparing a table against an expected dataset, the Cassandra-specific comparison rules, and the failure report. |
| Embedded server | The EmbeddedCassandraServerHelper API: starting, configuring ports and directories, cleaning between tests, and the one-instance-per-JVM constraint. |
| Spring integration | cassandra-unit-spring: the @EmbeddedCassandra, @CassandraDataSet and @CassandraUnit annotations with Spring's TestContext framework. |
| Troubleshooting | The failure modes that are hard to diagnose from their error messages. Check here first if a test JVM dies without explanation. |
| Migrating from 4.x | Everything removed or changed in 5.0.0, and what to do instead. |
Release-by-release detail lives in CHANGELOG.md. How to build and contribute is in CONTRIBUTING.md.
Which version these docs describe¶
These docs describe the 5.x line, and 5.2.0 is the current release on Maven Central. Everything on these pages is in it, including the fluent assertion API in Asserting in code and the Java dataset builder, both added by 5.2.0.
5.0.0 deliberately breaks compatibility with 4.3.1.0 — it upgrades the embedded server from Cassandra 3.11.5 to 5.0.8, requires JDK 17, and removes the command line tools, the shaded artifact and the 4.x XML/JSON/YAML dataset formats. If you are using 4.3.1.0 or earlier, these pages will not match what you have installed; see Migrating from 4.x for exactly what changed.
These pages replace the project wiki, which had drifted so far that it documented classes and annotation attributes that never existed. Documentation now lives in the repository so that it is versioned with the code and reviewed alongside it.