Testing¶

Unit Testing¶

The most simple way to test code in Cassandra is probably by writing a unit test. Cassandra uses JUnit as a testing framework and test cases can be found in the test/unit directory. Ideally you’d be able to create a unit test for your implementation that would exclusively cover the class you created (the unit under test). Unfortunately this is not always possible and Cassandra doesn’t have a very mock friendly code base. Often you’ll find yourself in a situation where you have to make use of an embedded Cassandra instance that you’ll be able to interact with in your test. If you want to make use of CQL in your test, you can simply extend CQLTester and use some of the convenient helper methods such as in the following example.

@Test
public void testBatchAndList() throws Throwable
{
   createTable("CREATE TABLE %s (k int PRIMARY KEY, l list<int>)");
   execute("BEGIN BATCH " +
           "UPDATE %1$s SET l = l +[ 1 ] WHERE k = 0; " +
           "UPDATE %1$s SET l = l + [ 2 ] WHERE k = 0; " +
           "UPDATE %1$s SET l = l + [ 3 ] WHERE k = 0; " +
           "APPLY BATCH");

   assertRows(execute("SELECT l FROM %s WHERE k = 0"),
              row(list(1, 2, 3)));
}

Unit tests can be run from the command line using the ant test command, ant test -Dtest.name=<simple_classname> to execute a test suite or ant testsome -Dtest.name=<FQCN> -Dtest.methods=<testmethod1>[,testmethod2] for individual tests. For example, to run all test methods in the org.apache.cassandra.cql3.SimpleQueryTest class, you would run:

ant test -Dtest.name=SimpleQueryTest

To run only the testStaticCompactTables() test method from that class, you would run:

ant testsome -Dtest.name=org.apache.cassandra.cql3.SimpleQueryTest -Dtest.methods=testStaticCompactTables

If you see an error like this:

Throws: cassandra-trunk/build.xml:1134: taskdef A class needed by class org.krummas.junit.JStackJUnitTask cannot be found:
org/apache/tools/ant/taskdefs/optional/junit/JUnitTask  using the classloader
AntClassLoader[/.../cassandra-trunk/lib/jstackjunit-0.0.1.jar]

You will need to install the ant-optional package since it contains the JUnitTask class.

DTests¶

One way of doing integration or system testing at larger scale is by using dtest, which stands for “Cassandra Distributed Tests”. The idea is to automatically setup Cassandra clusters using various configurations and simulate certain use cases you want to test. This is done using Python scripts and ccmlib from the ccm project. Dtests will setup clusters using this library just as you do running ad-hoc ccm commands on your local machine. Afterwards dtests will use the Python driver to interact with the nodes, manipulate the file system, analyze logs or mess with individual nodes.

Using dtests helps us to prevent regression bugs by continually executing tests on the CI server against new patches. Committers will be able to set up build branches there and your reviewer may use the CI environment to run tests for your patch. Read more on the motivation behind continuous integration here.

The best way to learn how to write dtests is probably by reading the introduction “How to Write a Dtest” and by looking at existing, recently updated tests in the project. New tests must follow certain style conventions that are being checked before accepting contributions. In contrast to Cassandra, dtest issues and pull-requests are managed on github, therefor you should make sure to link any created dtests in your Cassandra ticket and also refer to the ticket number in your dtest PR.

Creating a good dtest can be tough, but it should not prevent you from submitting patches! Please ask in the corresponding JIRA ticket how to write a good dtest for the patch. In most cases a reviewer or committer will able to support you, and in some cases they may offer to write a dtest for you.

Performance Testing¶

Performance tests for Cassandra are a special breed of tests that are not part of the usual patch contribution process. In fact you can contribute tons of patches to Cassandra without ever running performance tests. They are important however when working on performance improvements, as such improvements must be measurable.