Core - org.unittested:cassandra-test-core

Cassandra Test test environment agnostic components.

License

License

Categories

Categories

Cassandra Data Databases
GroupId

GroupId

org.unittested
ArtifactId

ArtifactId

cassandra-test-core
Last Version

Last Version

1.0.3
Release Date

Release Date

Type

Type

jar
Description

Description

Core - org.unittested:cassandra-test-core
Cassandra Test test environment agnostic components.
Project URL

Project URL

https://github.com/dananderson/cassandra-test

Download cassandra-test-core

How to add to project

<!-- https://jarcasting.com/artifacts/org.unittested/cassandra-test-core/ -->
<dependency>
    <groupId>org.unittested</groupId>
    <artifactId>cassandra-test-core</artifactId>
    <version>1.0.3</version>
</dependency>
// https://jarcasting.com/artifacts/org.unittested/cassandra-test-core/
implementation 'org.unittested:cassandra-test-core:1.0.3'
// https://jarcasting.com/artifacts/org.unittested/cassandra-test-core/
implementation ("org.unittested:cassandra-test-core:1.0.3")
'org.unittested:cassandra-test-core:jar:1.0.3'
<dependency org="org.unittested" name="cassandra-test-core" rev="1.0.3">
  <artifact name="cassandra-test-core" type="jar" />
</dependency>
@Grapes(
@Grab(group='org.unittested', module='cassandra-test-core', version='1.0.3')
)
libraryDependencies += "org.unittested" % "cassandra-test-core" % "1.0.3"
[org.unittested/cassandra-test-core "1.0.3"]

Dependencies

compile (1)

Group / Artifact Type Version
org.apache.commons : commons-lang3 jar 3.4

provided (1)

Group / Artifact Type Version
com.datastax.cassandra : cassandra-driver-core jar 3.0.2

test (6)

Group / Artifact Type Version
org.testng : testng jar 6.8.8
org.hamcrest : hamcrest-library jar 1.3
org.mockito : mockito-all jar 1.10.8
nl.jqno.equalsverifier : equalsverifier jar 1.7.8
log4j : log4j jar 1.2.17
org.slf4j : slf4j-log4j12 jar 1.7.6

Project Modules

There are no modules declared in this project.

Cassandra Test

Build Status codecov.io

Cassandra Test is a Java test framework for writing unit tests and integration tests against a Cassandra database.

Features

  • Connection management
  • Keyspace and schema management
  • Data loading from CQL files
  • Rollbacks
  • TestNG, JUnit 4 and Spring Test support
  • Backwards compatible with Java 6+, Cassandra 2.x & 3.x and Java Driver 2.x & 3.x
  • Highly configurable

Getting Cassandra Test

Cassandra Test publishes an artifact for each supported test framework.

Test Framework Cassandra Test Artifact
TestNG org.unittested:cassandra-test-testng:1.0.3
JUnit 4 org.unittested:cassandra-test-junit:1.0.3
Spring Test org.unittested:cassandra-test-spring:1.0.3

If your environment requires a custom integration, use the Cassandra Test Core artifact: org.unittested:cassandra-test-core:1.0.3. The TestEnvironmentAdapter can be used to connect test life cycle events to Cassandra Test.

Writing Tests

Using Test Framework Bindings

Each test framework has a slightly different way to bind with Cassandra Test. Once bound, any test in any test framework can use Cassandra Test annotations to configure Cassandra behavior.

TestNG

In the TestNG environment, tests can extend AbstractTestNGCassandraTest to be a Cassandra Test. Session and Cluster connection objects are available through this base class.

public class MyTest extends AbstractTestNGCassandraTest {
    @Test
    public cassandraTest() {
        ...
    }
}

JUnit 4

In the JUnit 4 environment, multiple binding options are available.

First, tests can extend AbstractJUnit4CassandraTest to be a Cassandra Test. Session and Cluster connection objects are available through this base class.

public class MyTest extends AbstractJUnit4CassandraTest {
    @Test
    public cassandraTest() {
        ...
    }
}

Second, tests can use CassandraClassRule and CassandraRule to be a Cassandra Test. Session and Cluster connection objects are available through the CassandraRule instance.

public class MyTest {
    @ClassRule
    public static CassandraClassRule classRule = new CassandraClassRule();

    @Rule
    public CassandraRule cassandraRule = new CassandraRule(classRule);

    @Test
    public cassandraTest() {
        ...
    }
}

Spring Test

In the Spring Test environment, tests add SpringCassandraTestExecutionListener to be a Cassandra Test. Session and Cluster connection objects are available through the Autowire-like annotation @CassandraBean.

@TestExecutionListeners(value = SpringCassandraTestExecutionListener.class, mergeMode = MERGE_WITH_DEFAULTS)
public class MyTest extends AbstractTestNGSpringContextTests {

    @CassandraBean
    private Session session;

    @Test
    public cassandraTest() {
        ...
    }
}

Configuration

Cassandra Tests can be configured through Java annotations.

Connection

When a test is bound to Cassandra Test, the test will automatically try to connect to a Cassandra cluster at 127.0.0.1:9042 with no authentication. If the connection requires a different configuration, @CassandraConnect can be used.

@Connect(host = "127.0.0.2", user = "cassandra", password = "cassandra")
public class MyTest extends AbstractTestNGCassandraTest {
    @Test
    public cassandraTest() {
        ...
    }
}

Keyspace and Schema

The primary use case for Cassandra Test is to run tests against a single keyspace. Cassandra Test manages this keyspace by installing schema, detecting schema modifications and rebuilding schema as necessary to maintain consistent state across tests.

The @CassandraKeyspace annotation gives Cassandra Test full control of a keyspace. The annotation describes how to create the keyspace and how to create it's schema. If Cassandra Test detects that a keyspace has been altered from this state, Cassandra Test will drop and re-create the keyspace before the next test run.

@CassandraKeyspace(value = "my_keyspace", schema = "classpath:my_keyspace_schema.cql")
public class MyTest extends AbstractTestNGCassandraTest {
    @Test
    public cassandraTest() {
        ...
    }
}

The @CassandraImportKeyspace annotation declares a schema and keyspace that has been configured outside of the control of Cassandra Test. Cassandra Test cannot re-create or drop this keyspace. If a test modifies the keyspace schema in any way, the test automatically fails.

@CassandraImportKeyspace("my_keyspace")
public class MyTest extends AbstractTestNGCassandraTest {
    @Test
    public cassandraTest() {
        ...
    }
}

Data Loading

Table data can be loaded using the @CassandraData annotation. Currently, data loading supports CQL files containing CQL statements delimited by ";". The format is exactly the same as CQL files executable by cqlsh.

@CassandraKeyspace(value = "my_keyspace", schema = "classpath:my_keyspace_schema.cql")
@CassandraData("classpath:my_keyspace_table_data.cql")
public class MyTest extends AbstractTestNGCassandraTest {
    @Test
    public cassandraTest() {
        ...
    }
}

Rollback

When a test completes, Cassandra Test will perform a pseudo-rollback or clean up of the keyspace. The clean up can be truncation of keyspace tables or dropping the keyspace. The rollback behavior is configured through the @CassandraRollback annotation.

@CassandraKeyspace(value = "my_keyspace", schema = "classpath:my_keyspace_schema.cql")
@CassandraData("classpath:my_keyspace_table_data.cql")
@CassandraRollback(afterClass=RollbackStrategy.DROP)
public class MyTest extends AbstractTestNGCassandraTest {
    @Test
    public cassandraTest() {
        ...
    }
}

Properties

For larger projects, hard coding keyspace names and hosts in annotations may not be clean or practical. Cassandra Test supports property references in annotations to address the problem. Properties are sourced from a Java properties file. By default, /cassandra-test.properties from the class path is used. Otherwise, a properties file can be specified with the @CassandraProperties annotation.

@CassandraImportKeyspace("${cassandra.test.keyspace}")
public class MyTest extends AbstractTestNGCassandraTest {
    @Test
    public cassandraTest() {
        ...
    }
}

Compatibility

Cassandra Test has been built and tested with:

Technology Supported Versions
Datastax Java Driver 2.0.2+, 2.1.0+, 3.0.0+
Apache Cassandra 2.0.4+, 2.1.0+, 2.2.0+, 3.0.0+
Java 6+

License

Apache License, Version 2.0

Contributing

Pull requests for bug fixes and new features are welcome.

The following items are being considered for future releases of Cassandra Test.

  • Improve README documentation across the project.
  • Wiki documentation.
  • Create an example usage project.
  • Add method level annotations.
  • Investigate other data loading source file formats, including JSON, YAML, XML and CSV.
  • Investigate "golden" data for table data state verification.
  • Add plugins for schema management tools.
  • Investigate support for managing Cassandra instances with CCM, Embedded Cassandra and SCassandra.
  • Investigate negative testing tools to put Cassandra into bad states (node down, etc).
  • Performance: session cache, file read cache, etc.
  • Parallel test support (why?).

Versions

Version
1.0.3
1.0.2
1.0.1
1.0.0