Learn how to use Testcontainers to create lightweight, throwaway instances of ScyllaDB for testing
Why wrestle with all the complexities of database configuration for each round of integration testing? In this blog post, we will explain how to use the Testcontainers library to provide lightweight, throwaway instances of ScyllaDB for testing. We’ll go through a hands-on example that includes creating the database instance and testing against it.
Testcontainers: A Valuable Tool for Integration Testing with ScyllaDB
You automatically unit test your code and (hopefully) integration test your system…but what about your database? To rest assured that the application works as expected, you need to extend beyond unit testing. You also need to automatically test how the units interact with one another and how they interact with external services and systems (message brokers, data stores, and so on). But running those integration tests requires the infrastructure to be configured correctly, with all the components set to the proper state. You also need to ensure that the tests are isolated and don’t produce any side effects or “test pollution.” How do you reduce the pain…and get it all running in your CI/CD process?
This is where Testcontainers comes into play. Testcontainers is an open source library for throwaway, lightweight instances of databases (including ScyllaDB), message brokers, web browsers, or just about anything that can run in a Docker container. You define your dependencies in code, which makes it well-suited for CI/CD processes.
When you run your tests, a ScyllaDB container will be created and then deleted. This allows you to test your application against a real instance of the database without having to worry about complex environment configurations. It also ensures that the database setup has no effect on the production environment.
Some of the advantages of using Testcontainers with ScyllaDB:
It launches Dockerized databases on demand, so you get a fresh environment for every test run.
It isolates tests with throwaway containers. There’s no test interference or state leakage since each test gets a pristine database state
Tests are fast and realistic, since the container starts in seconds, ScyllaDB responds fast, and actual CQL responses are used.
Tutorial: Building a ScyllaDB Test Step-by-Step
The Testcontainers ScyllaDB integration works with Java, Go, Python (see example here), and Node.js. Here, we’ll walk through an example of how to use it with Java.The steps described below are applicable to any programming language and its corresponding testing framework. In our specific Java example, we will be using the JUnit 5 testing framework.
The integration between Testcontainers and ScyllaDB uses Docker. You can read more about using ScyllaDB with Docker, and learn the Best Practices for Running ScyllaDB on Docker.
Step 1: Configure Your Project Dependencies
Before we begin, make sure you have:
Java 21 or newer installed
Docker installed and running (required for Testcontainers)
Gradle 8
Note: If you are more comfortable with Maven, you can still follow this tutorial, but the setup and test execution steps will be different.
To verify that Java 21 or newer is installed, run:
java --version
To verify that Docker is installed and running correctly, run:
docker run hello-world
To verify that Gradle 8 or newer is installed, run:
gradle --version
Once you have verified that all of the relevant project dependencies are installed and ready, you can move on to creating a new project.
mkdir testcontainers-scylladb-java
cd testcontainers-scylladb-java
gradle init
A series of prompts will appear. Here are the relevant choices you need to select:
Select application
Select java
Enter Java version: 21
Enter project name: testcontainers-scylladb-java
Select application structure: Single application project
Select build script DSL: Groovy
Select test framework: JUnit Jupiter
For “Generate build using new APIs and behavior” select no
After that part is finished, to verify the successful initialization of the new project, run:
./gradlew --version
If everything goes well, you should see a build.gradle file in the app folder.
You will need to add the following dependencies in your app/build.gradle file:
dependencies {
// Use JUnit Jupiter for testing.
testImplementation libs.junit.jupiter
testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
// This dependency is used by the application.
implementation libs.guava
// Add the required dependencies for the test
testImplementation 'org.testcontainers:scylladb:1.20.5'
testImplementation 'com.scylladb:java-driver-core:4.18.1.0'
implementation 'ch.qos.logback:logback-classic:1.4.11'
}
Also, to get test report output in the terminal, you will need to add testLogging to app/build.gradle file as well:
tasks.named('test') { // Use JUnit Platform for unit tests.
useJUnitPlatform()
// Add this testLogging configuration to get
// the test results in terminal
testLogging {
events "passed", "skipped", "failed"
showStandardStreams = true
exceptionFormat = 'full'
showCauses = true
}
}
Once you’re finished editing the app/build.gradle file, you need to install the dependencies by running this command in the terminal:
./gradlew build
You should see the BUILD SUCCESSFUL output in the terminal.
The final preparation step is to create a ScyllaDBExampleTest.java file somewhere in the src/test/java folder. JUnit will find all tests in the src/test/java folder.
For example:
touch src/test/java/org/example/ScyllaDBExampleTest.java
Step 2: Launch ScyllaDB in a Container
Once the dependencies are installed and the ScyllaDBExampleTest.java file created, you can copy and paste the code provided below to the ScyllaDBExampleTest.java file.
This code will start a fresh ScyllaDB instance for every test in this file in the setUp method.
To ensure the instance will get shut down after every test, we’ve created the tearDown method, too.
Step 3: Connect via the Java Driver
You’ll connect to the ScyllaDB container by creating a new session.
To do so, you’ll need to update your setUp method in the ScyllaDBExampleTest.java file:
Step 4: Define Your Schema
Now that you have the code to run ScyllaDB and connect to it, you can use the connection to create the schema for the database.
Let’s define the schema by updating your setUp method in the ScyllaDBExampleTest.java file:
Step 5: Insert and Query Data
Once you have prepared the ScyllaDB instance, you can run operations on it.
To do so, let’s add a new method to our ScyllaDBExampleTest class in the ScyllaDBExampleTest.java file:
Step 6: Run and Validate the Test
Your test is now complete and ready to be executed!
Use the following command to execute the test:
./gradlew clean test --no-daemon
If the execution is successful, you’ll notice the container starting in the logs, and the test will pass if the assertions are met.
Here’s an example of what a successful terminal output might look like:
12:05:26.708 [Test worker] DEBUG com.github.dockerjava.zerodep.shaded.org.apache.hc.client5.http.impl.io.PoolingHttpClientConnectionManager -- ep-00000012: connection released [route: {}->unix://localhost:2375][total available: 1; route allocated: 1 of 2147483647; total allocated: 1 of 2147483647]
12:05:26.708 [Test worker] DEBUG org.testcontainers.utility.ResourceReaper -- Removed container and associated volume(s): scylladb/scylla:2025.1
ScyllaDBExampleTest > testScyllaDBOperations() PASSED
BUILD SUCCESSFUL in 35s 3 actionable tasks: 3 executed
Full code example
The repository for the full code example can be found here: https://github.com/scylladb/scylla-code-samples/tree/master/java-testcontainers
Level Up: Extending Your ScyllaDB Tests
That’s just the basics. Here are some additional uses you might want to explore on your own:
Test schema migrations – Verify that your database evolution scripts work correctly
Simulate multi-node clusters – Use multiple containers to test your application with multi-node and multi-dc scenarios
Benchmark performance – Measure your application’s throughput under various workloads
Test failure scenarios – Simulate how your application handles network partitions or node failures
Wrap-Up: Master ScyllaDB Testing with Confidence
You’ve built a fast, real ScyllaDB test in Java that provides realistic database behavior without the overhead of a permanent installation. This approach should give you confidence that your code will work correctly in production.
You can try it with an example app on ScyllaDB University, customize it to your project and specific needs, and share your experience with the community!
Resources: Dive Deeper
ScyllaDB DocumentationScyllaDB with DockerBest Practices for Running ScyllaDB on DockerTestcontainersGitHub Repository with ExamplesScyllaDB University – Free courses to master ScyllaDB
