kandra-test

kandra-test is Kandra's test-support module, io.kandra.test.*, offering two genuinely different testing styles for code that uses KandraRepository/KandraSuspendRepository:

Read the limitation section below before picking a style — the fake-session path is not a drop-in replacement for the container path today; it's narrower than its own class-level KDoc claims.

Why this exists as a separate module

kandra-test depends on kandra-core and kandra-runtime (implementation) plus, notably, compileOnly(libs.testcontainers.cassandra) — Testcontainers is not forced onto every consumer's runtime classpath just because they add kandra-test for FakeKandraSession; only a consumer who actually calls KandraTestcontainers needs to also bring Testcontainers themselves at test time. As a test-only module in the first place, keeping it separate from kandra-core/kandra-runtime means production code never accidentally pulls in JUnit, Testcontainers, or a fake driver implementation — kandra-test is meant to be a testImplementation, never an implementation, dependency.

FakeKandraSession

class FakeKandraSession : CqlSession

An in-process implementation of the DataStax driver's CqlSession interface — no network, no ScyllaDB process.

class FakeKandraSessionCaptureTest {
    private val fakeSession = FakeKandraSession()
 
    @AfterEach
    fun tearDown() { fakeSession.reset() }
 
    @Test
    fun `execute captures batch statements for inspection`() {
        // SimpleStatement doesn't need prepare()/bind(), so it works fine under the fake.
        val batch = BatchStatement.newInstance(DefaultBatchType.LOGGED)
            .add(SimpleStatement.newInstance("INSERT INTO users (id, name) VALUES (?, ?)", "u1", "Ada"))
            .add(SimpleStatement.newInstance("INSERT INTO user_email_lookup (email, id) VALUES (?, ?)", "ada@x.com", "u1"))
 
        val result = fakeSession.execute(batch)
 
        assertEquals(1, fakeSession.capturedBatches().size)
        assertEquals(2, fakeSession.capturedBatches().single().size)
        assertEquals(true, result.wasApplied())   // always true — cannot simulate LWT failure here
    }
}

KandraTestUtils.inMemory(...) / io.kandra.test.KandraRuntime

object KandraTestUtils {
    fun inMemory(vararg classes: KClass<*>): KandraRuntime
}
 
class KandraRuntime internal constructor(val session: CqlSession) : AutoCloseable {
    fun <T : Any> repository(klass: KClass<T>): KandraRepository<T>
    fun <T : Any> suspendRepository(klass: KClass<T>): KandraSuspendRepository<T>
    override fun close()   // cancels pending eventual-write coroutines; does NOT close session or clear SchemaRegistry
}

@Test
fun `repository calls currently throw through the fake session`() {
    val runtime = KandraTestUtils.inMemory(User::class)
    val repo = runtime.repository(User::class)
 
    org.junit.jupiter.api.assertThrows<UnsupportedOperationException> {
        repo.save(User(id = "u1", name = "Ada"))
    }
 
    runtime.close()
    SchemaRegistry.clear()   // schema registration is process-global — reset between tests
}

inMemory(...) calls SchemaRegistry.register(it) for each class (additive, process-global — never cleared automatically) and returns a KandraRuntime wrapping a fresh FakeKandraSession.

KandraTestcontainers

object KandraTestcontainers {
    val container: CassandraContainer<*>
    fun freshKeyspace(vararg classes: KClass<*>): KandraRuntimeHandle
}
 
class KandraRuntimeHandle(
    val runtime: io.kandra.runtime.KandraRuntime,   // the real production runtime, not a test double
    val keyspace: String,
) {
    inline fun <reified T : Any> repository(): KandraRepository<T>
    inline fun <reified T : Any> suspendRepository(): KandraSuspendRepository<T>
    fun close()
}

container is by lazy { CassandraContainer("cassandra:4.1").withExposedPorts(9042).also { it.start() } } — Kotlin's default by lazy mode is SYNCHRONIZED, so this is a thread-safe singleton shared across every test class in the same JVM. .start() runs inside the lazy initializer itself, so the very first access from any test class blocks synchronously while Testcontainers pulls/starts the container — can take tens of seconds on a cold Docker cache. There is no shutdown code anywhere in this file; the container runs until the JVM exits and Testcontainers' Ryuk reaper cleans it up.

freshKeyspace(vararg classes):

1. Generates keyspace = "kandra_test_${UUID.randomUUID()...}" — fresh per call, so concurrent test classes never collide.
2. Opens a throwaway bootstrap session, runs CREATE KEYSPACE IF NOT EXISTS ... SimpleStrategy, replication_factor = 1, closes it.
3. Opens a second, real session with .withKeyspace(keyspace) — the session everything else uses.
4. For each class: SchemaRegistry.register(klass) (same process-global registry as the fake-session path), then executes every statement from DdlGenerator.allStatements(schema) — real CREATE TABLE (and @LookupIndex lookup tables) against the container.
5. Builds StatementBuilder, a fresh CoroutineScope, BatchEngine, and the production io.kandra.runtime.KandraRuntime — the same class Ktor wires up in real apps, not a test double.

class UserRepositoryIntegrationTest {
    private val db = KandraTestcontainers.freshKeyspace(User::class)
    private val userRepo = db.repository<User>()             // reified — no ::class argument
    private val userSuspendRepo = db.suspendRepository<User>()
 
    @AfterEach
    fun tearDown() {
        db.close()   // drops db.keyspace and closes db's own session; the shared container stays up
    }
 
    @Test
    fun `save then findById round-trips through real ScyllaDB-compatible CQL`() {
        val user = User(id = "u1", name = "Ada", email = "ada@example.com")
        userRepo.save(user)
        assertEquals(user, userRepo.findById(user.id))
    }
}

Gotchas worth double-checking in review

• SchemaRegistry is process-global and neither test style clears it automatically — call SchemaRegistry.clear() yourself in @AfterEach if a test depends on a clean registry (e.g. asserting a schema-validation failure that only fires on first registration).
• FakeKandraSession.tableContents(...) always returns emptyList() — never use it to assert on saved data; there is nothing behind it.
• FakeResultSet.wasApplied() is hardcoded true, with no seam to flip it — you cannot simulate a failed LWT (saveIfNotExists() == false, an optimistic-lock conflict) through FakeKandraSession. Testcontainers is the only way to exercise those paths.
• The first integration test to touch KandraTestcontainers.container in a JVM run is noticeably slower than the rest — it's paying for the container start that every subsequent freshKeyspace() call reuses.

Full API reference

kandra-test on Dokka → · FakeKandraSession → · KandraTestcontainers →

Where this shows up elsewhere on this site

• /battle-scars/testing-lwt-and-fakes — the full story behind FakeKandraSession's current limitations, including ISS-020.
• /philosophy/testing — when to reach for the fake vs. Testcontainers.
• /tutorial/12-testing — both styles in a working test suite.