CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-org-testcontainers--cassandra

Testcontainers implementation for Apache Cassandra, providing lightweight, throwaway database instances for Java integration testing

Overview
Eval results
Files

configuration-initialization.mddocs/

Configuration and Initialization

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

Capabilities

Configuration Override

Replace the default Cassandra configuration with custom configuration files from the classpath.

/**
 * Initialize Cassandra with custom overridden Cassandra configuration.
 * Docker effectively replaces all /etc/cassandra content with the content of config location,
 * so if cassandra.yaml in configLocation is absent or corrupted, Cassandra won't launch.
 * 
 * @param configLocation relative classpath with the directory that contains cassandra.yaml 
 *                      and other configuration files
 * @return CassandraContainer instance for method chaining
 */
public CassandraContainer withConfigurationOverride(String configLocation);

Usage Examples:

import org.testcontainers.cassandra.CassandraContainer;

// Use custom configuration from classpath
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
    .withConfigurationOverride("my-cassandra-config");

// Configuration directory structure in src/test/resources:
// my-cassandra-config/
// ├── cassandra.yaml          (required - main configuration)
// ├── cassandra-rackdc.properties
// └── logback.xml
cassandra.start();

Configuration Requirements:

  • The configuration directory must contain a valid cassandra.yaml file
  • All files in the directory will replace the default /etc/cassandra content
  • Configuration files must be accessible via the classpath
  • Invalid or missing cassandra.yaml will cause container startup failure

Common Configuration Use Cases:

// Enable authentication
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
    .withConfigurationOverride("cassandra-auth-config");

// Custom cluster settings
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")  
    .withConfigurationOverride("cassandra-cluster-config");

// Performance tuning for tests
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
    .withConfigurationOverride("cassandra-test-optimized");

Initialization Scripts

Execute CQL scripts after container startup to prepare test data and database schema.

/**
 * Initialize Cassandra with init CQL script.
 * CQL script will be applied after container is started (using WaitStrategy).
 * 
 * @param initScriptPath relative classpath resource path to CQL script
 * @return CassandraContainer instance for method chaining
 */
public CassandraContainer withInitScript(String initScriptPath);

Usage Examples:

import org.testcontainers.cassandra.CassandraContainer;

// Execute initialization script from classpath
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
    .withInitScript("init-schema.cql");

// Chain with configuration override
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
    .withConfigurationOverride("cassandra-auth-config")
    .withInitScript("init-with-auth.cql");

Example Initialization Script (init-schema.cql):

-- Create keyspace
CREATE KEYSPACE IF NOT EXISTS test_keyspace 
WITH replication = {'class': 'SimpleStrategy', 'replication_factor': 1};

-- Use keyspace
USE test_keyspace;

-- Create table
CREATE TABLE IF NOT EXISTS users (
    id UUID PRIMARY KEY,
    username text,
    email text,
    created_at timestamp
);

-- Insert test data
INSERT INTO users (id, username, email, created_at) 
VALUES (uuid(), 'testuser', 'test@example.com', toTimestamp(now()));

Script Execution Process:

  1. Container starts and becomes ready (via wait strategy)
  2. Script is copied into the container as a temporary file
  3. Script is executed using cqlsh command inside the container
  4. Execution success/failure is reported via logs
  5. Temporary script file is cleaned up

Error Handling:

import org.testcontainers.ext.ScriptUtils.ScriptLoadException;
import org.testcontainers.ext.ScriptUtils.UncategorizedScriptException;

try (CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
    .withInitScript("nonexistent-script.cql")) {
    cassandra.start();
} catch (ScriptLoadException e) {
    // Script file not found in classpath
    logger.error("Init script not found", e);
} catch (UncategorizedScriptException e) {
    // CQL execution error
    logger.error("Init script execution failed", e);
}

Combined Configuration and Initialization

Common pattern combining custom configuration with initialization scripts for complex test setups.

Usage Example:

// Complete setup with authentication and test data
CassandraContainer cassandra = new CassandraContainer("cassandra:3.11.2")
    .withConfigurationOverride("cassandra-auth-enabled")
    .withInitScript("setup-auth-and-data.cql");

cassandra.start();

// Connect with authentication
CqlSession session = CqlSession.builder()
    .addContactPoint(cassandra.getContactPoint())
    .withLocalDatacenter(cassandra.getLocalDatacenter())
    .withAuthCredentials(cassandra.getUsername(), cassandra.getPassword())
    .build();

Execution Order:

  1. Container is created with specified Docker image
  2. Configuration override is applied (if specified)
  3. Container starts with custom configuration
  4. Wait strategy ensures Cassandra is ready for connections
  5. Initialization script is executed (if specified)
  6. Container is ready for test connections

Error Scenarios

Configuration Override Errors

  • ContainerLaunchException: Thrown when configuration directory is empty or cassandra.yaml is invalid
  • IllegalArgumentException: Thrown when configuration path cannot be resolved from classpath

Initialization Script Errors

  • ScriptLoadException: Thrown when script file cannot be found in classpath
  • ScriptStatementFailedException: Thrown when CQL statement execution fails
  • UncategorizedScriptException: Thrown for general script execution errors

Install with Tessl CLI

npx tessl i tessl/maven-org-testcontainers--cassandra

docs

configuration-initialization.md

connection-access.md

container-management.md

index.md

wait-strategies-delegation.md

tile.json