0
# Testcontainers Cassandra
1

2
Testcontainers implementation for Apache Cassandra that provides lightweight, throwaway instances of Cassandra databases for Java integration testing. This library extends the Testcontainers framework with Cassandra-specific functionality, offering Docker-based container management with automatic configuration, CQL script initialization, and seamless integration with DataStax drivers.
3

4
## Package Information
5

6
- **Package Name**: org.testcontainers:cassandra
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add to your Maven `pom.xml`:
10

11
```xml
12
<dependency>
13
    <groupId>org.testcontainers</groupId>
14
    <artifactId>cassandra</artifactId>
15
    <version>1.21.3</version>
16
    <scope>test</scope>
17
</dependency>
18
```
19

20
For Gradle:
21

22
```gradle
23
testImplementation 'org.testcontainers:cassandra:1.21.3'
24
```
25

26
## Core Imports
27

28
```java
29
import org.testcontainers.cassandra.CassandraContainer;
30
```
31

32
For DataStax driver integration:
33

34
```java
35
import com.datastax.oss.driver.api.core.CqlSession;
36
import java.net.InetSocketAddress;
37
```
38

39
## Basic Usage
40

41
```java
42
import org.testcontainers.cassandra.CassandraContainer;
43
import com.datastax.oss.driver.api.core.CqlSession;
44
import com.datastax.oss.driver.api.core.cql.ResultSet;
45
import org.junit.Test;
46
import static org.assertj.core.api.Assertions.assertThat;
47

48
public class CassandraTest {
49
    @Test
50
    public void testWithCassandra() {
51
        try (CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")) {
52
            cassandra.start();
53
            
54
            // Create CQL session using DataStax driver 4.x
55
            CqlSession session = CqlSession.builder()
56
                .addContactPoint(cassandra.getContactPoint())
57
                .withLocalDatacenter(cassandra.getLocalDatacenter())
58
                .build();
59
            
60
            // Execute queries
61
            ResultSet result = session.execute("SELECT release_version FROM system.local");
62
            assertThat(result.wasApplied()).isTrue();
63
            
64
            session.close();
65
        }
66
    }
67
}
68
```
69

70
## Architecture
71

72
The Cassandra Testcontainers module is built around several key components:
73

74
- **Container Management**: Extends `GenericContainer` providing Docker lifecycle management for Cassandra instances
75
- **Configuration Override**: Support for custom cassandra.yaml and configuration files via classpath resources
76
- **Initialization Scripts**: CQL script execution system for database setup and seeding
77
- **Wait Strategies**: Custom wait strategy that ensures Cassandra is ready for queries before test execution
78
- **Driver Integration**: Seamless integration with both legacy DataStax driver 3.x and modern driver 4.x
79
- **Authentication Support**: Built-in support for Cassandra authentication when enabled
80

81
## Capabilities
82

83
### Container Management
84

85
Core functionality for creating, configuring, and managing Cassandra Docker containers with proper lifecycle management and resource cleanup.
86

87
```java { .api }
88
public class CassandraContainer extends GenericContainer<CassandraContainer> {
89
    public CassandraContainer(String dockerImageName);
90
    public CassandraContainer(DockerImageName dockerImageName);
91
}
92
```
93

94
[Container Management](./container-management.md)
95

96
### Configuration and Initialization
97

98
Configuration override capabilities and CQL script initialization for custom Cassandra setups and test data preparation.
99

100
```java { .api }
101
public CassandraContainer withConfigurationOverride(String configLocation);
102
public CassandraContainer withInitScript(String initScriptPath);
103
```
104

105
[Configuration and Initialization](./configuration-initialization.md)
106

107
### Connection and Access
108

109
Methods for obtaining connection information and establishing DataStax driver sessions for query execution.
110

111
```java { .api }
112
public InetSocketAddress getContactPoint();
113
public String getLocalDatacenter();
114
public String getUsername();
115
public String getPassword();
116
```
117

118
[Connection and Access](./connection-access.md)
119

120
### Wait Strategies and Database Delegation
121

122
Advanced wait strategies and database operation delegation for ensuring container readiness and executing database operations.
123

124
```java { .api }
125
public class CassandraQueryWaitStrategy extends AbstractWaitStrategy;
126
public class CassandraDatabaseDelegate extends AbstractDatabaseDelegate<Void>;
127
```
128

129
[Wait Strategies and Database Delegation](./wait-strategies-delegation.md)
130

131
## Environment Configuration
132

133
The container automatically configures the following Cassandra environment variables for optimal testing performance:
134

135
- `CASSANDRA_SNITCH`: "GossipingPropertyFileSnitch"
136
- `JVM_OPTS`: "-Dcassandra.skip_wait_for_gossip_to_settle=0 -Dcassandra.initial_token=0"
137
- `HEAP_NEWSIZE`: "128M"
138
- `MAX_HEAP_SIZE`: "1024M"
139
- `CASSANDRA_ENDPOINT_SNITCH`: "GossipingPropertyFileSnitch"  
140
- `CASSANDRA_DC`: "datacenter1" (configurable)
141

142
## Types
143

144
```java { .api }
145
// Container state interface for accessing container information
146
interface ContainerState {
147
    String getHost();
148
    Integer getMappedPort(int originalPort);
149
    Map<String, String> getEnvMap();
150
}
151

152
// Docker image name utility
153
class DockerImageName {
154
    static DockerImageName parse(String imageNameString);
155
    DockerImageName withTag(String tag);
156
    void assertCompatibleWith(DockerImageName expectedImageName);
157
}
158
```