Philip Thompson

<h3>What are Dtests?</h3>

<p>Apache Cassandra’s functional test suite, cassandra-dtest, short for “distributed tests”, is an&nbsp;<a href="https://github.com/riptano/cassandra-dtest">open-source Python project</a>&nbsp;on GitHub where much of the Apache Cassandra test automation effort takes place. Unlike Cassandra’s unit tests, the dtests are end-to-end, black box tests that run against Cassandra clusters via&nbsp;<a href="https://www.datastax.com/dev/blog/ccm-a-development-tool-for-creating-local-cassandra-clusters">CCM</a>. The Cassandra Cluster Manager, or CCM, is a Python library that runs local C* clusters by hosting multiple JVMs on the same box. Each test’s runtime is anywhere from thirty seconds to several minutes. Many are general purpose functional tests, while others are regression tests for specific tickets from the Apache Cassandra JIRA.</p>

<h3>Where are Dtests used?</h3>

<p>Continuous integration for dtests runs on a publicly accessible Jenkins server at&nbsp;<a href="http://cassci.datastax.com/">cassci.datastax.com</a>. As patches are written, contributors can use CassCI to run the C* unit tests and the dtest suite against their new code, as discussed&nbsp;<a href="https://www.datastax.com/dev/blog/cassandra-testing-improvements-for-developer-convenience-and-confidence">here</a>.</p>

<h3>Writing a Dtest</h3>

<p>Adding a new dtest is quite simple. You’ll want to choose the appropriate module and/or test suite for your new test, or add one if necessary. Add a new test method to the file you’ve chosen; make sure that “test” is in the method name, or nosetests won’t pick it up. Now is a good time to add your test’s docstring. The docstring should include a description of what your test is trying to verify and how, as well as some&nbsp;<a href="http://www.stack.nl/~dimitri/doxygen/">doxygen markup</a>. See dtest’s&nbsp;<a href="https://github.com/riptano/cassandra-dtest/blob/master/CONTRIBUTING.md">contributing.md</a>&nbsp;for more on the appropriate doxygen annotations to use.</p>

<p>Now that the boilerplate is taken care of, you’re ready to begin writing your test. The first step is to launch a C* cluster, like so:</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p>1</p>

			<p>2</p>
			</td>
			<td>
			<p><code>cluster </code><code>=</code> <code>self</code><code>.cluster</code></p>

			<p><code>cluster.populate(</code><code>3</code><code>).start(wait_for_binary_proto</code><code>=</code><code>True</code><code>)</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>You can modify the number of nodes in the cluster, the number of datacenters, or any of the cassandra.yaml options.</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p>1</p>

			<p>2</p>

			<p>3</p>
			</td>
			<td>
			<p><code>cluster </code><code>=</code> <code>self</code><code>.cluster</code></p>

			<p><code>cluster.set_configuration_options(values</code><code>=</code><code>{</code><code>'hinted_handoff_enabled'</code><code>: </code><code>False</code><code>}) </code><code># Set a cassandra.yaml option</code></p>

			<p><code>cluster.populate([</code><code>2</code><code>, </code><code>2</code><code>]).start(wait_for_binary_proto</code><code>=</code><code>True</code><code>) </code><code># A four node cluster. Two nodes in each of two datacenters</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>Remember that this is using CCM, so all of these processes are running on your laptop. Thus, it’s best not to launch more than five nodes. Most tests run against three nodes.</p>

<p>To create an object representing a connection to your C* cluster, you’ll want to use one of the following methods from dtest.py:</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p>1</p>

			<p>2</p>

			<p>3</p>

			<p>4</p>
			</td>
			<td>
			<p><code>def</code> <code>cql_connection(</code><code>self</code><code>, node)</code></p>

			<p><code>def</code> <code>exclusive_cql_connection(</code><code>self</code><code>, node)</code></p>

			<p><code>def</code> <code>patient_cql_connection(</code><code>self</code><code>, node)</code></p>

			<p><code>def</code> <code>patient_exclusive_cql_connection(</code><code>self</code><code>, node)</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>Use patient_cql_connection, unless you have a specific need for one of the others.</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p>1</p>

			<p>2</p>

			<p>3</p>

			<p>4</p>

			<p>5</p>
			</td>
			<td>
			<p><code>cluster </code><code>=</code> <code>self</code><code>.cluster</code></p>

			<p><code>cluster.populate(</code><code>3</code><code>).start(wait_for_binary_proto</code><code>=</code><code>True</code><code>)</code></p>

			<p><code>node1, node2, node3 </code><code>=</code> <code>cluster.nodelist()</code></p>

			<p>&nbsp;</p>

			<p><code>session </code><code>=</code> <code>self</code><code>.patient_cql_connection(node1)</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>From here out will be the actual testing logic. You can use the&nbsp;<a href="http://datastax.github.io/python-driver/getting_started.html#getting-started">Python driver</a>&nbsp;to interact with C*, mostly via CQL, or the ccmlib API to run cassandra-stress, nodetool, or any other tool that ships in the C* source.</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p>1</p>

			<p>2</p>

			<p>3</p>

			<p>4</p>

			<p>5</p>
			</td>
			<td>
			<p><code>session.execute(</code><code>"CREATE KEYSPACE ks WITH replication = { 'class':'SimpleStrategy', 'replication_factor':1} AND DURABLE_WRITES = true"</code><code>)</code></p>

			<p><code>session.execute(</code><code>"USE ks"</code><code>)</code></p>

			<p><code>session.execute(</code><code>"CREATE TABLE t (id int PRIMARY KEY, v int)"</code><code>)</code></p>

			<p><code>session.execute(</code><code>"INSERT INTO t (id, v) VALUES (1, 2)"</code><code>)</code></p>

			<p><code>rows </code><code>=</code> <code>session.execute(</code><code>"SELECT * FROM t"</code><code>)</code></p>
			</td>
		</tr>
	</tbody>
</table>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p>1</p>

			<p>2</p>

			<p>3</p>

			<p>4</p>

			<p>5</p>
			</td>
			<td>
			<p><code>node1, node2, node3 </code><code>=</code> <code>cluster.nodelist()</code></p>

			<p>&nbsp;</p>

			<p><code>node1.stress([</code><code>'write'</code><code>, </code><code>'n=1M'</code><code>, </code><code>'-rate'</code><code>, </code><code>'threads=10'</code><code>])</code></p>

			<p><code>node2.decommission()</code></p>

			<p><code>node3.repair()</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>You can use&nbsp;<a href="https://github.com/riptano/cassandra-dtest/blob/master/tools/assertions.py">assertions.py</a>&nbsp;and Python unittest’s&nbsp;<a href="https://docs.python.org/2/library/unittest.html#assert-methods">built-in assertions</a>&nbsp;to assert C*’s correctness.</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p>1</p>

			<p>2</p>

			<p>3</p>

			<p>4</p>

			<p>5</p>

			<p>6</p>

			<p>7</p>
			</td>
			<td>
			<p><code>from</code> <code>assertions </code><code>import</code> <code>assert_one</code></p>

			<p>&nbsp;</p>

			<p><code>session.execute(</code><code>"CREATE KEYSPACE ks WITH replication = { 'class':'SimpleStrategy', 'replication_factor':1} AND DURABLE_WRITES = true"</code><code>)</code></p>

			<p><code>session.execute(</code><code>"USE ks"</code><code>)</code></p>

			<p><code>session.execute(</code><code>"CREATE TABLE t (id int PRIMARY KEY, v int)"</code><code>)</code></p>

			<p><code>session.execute(</code><code>"INSERT INTO t (id, v) VALUES (1, 2)"</code><code>)</code></p>

			<p><code>assert_one(session, </code><code>"SELECT * FROM t"</code><code>, [</code><code>1</code><code>, </code><code>2</code><code>])</code></p>
			</td>
		</tr>
	</tbody>
</table>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p>1</p>

			<p>2</p>

			<p>3</p>
			</td>
			<td>
			<p><code>rows </code><code>=</code> <code>list</code><code>(session.execute(</code><code>"SELECT * FROM t"</code><code>))</code></p>

			<p><code>self</code><code>.assertEqual(rows[</code><code>0</code><code>], </code><code>1</code><code>)</code></p>

			<p><code>self</code><code>.assertEqual(rows[</code><code>1</code><code>], </code><code>2</code><code>)</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>Make sure you only use these, and not the Python assert keyword, as they offer significantly improved debug output on failures.</p>

<table border="0" cellpadding="0" cellspacing="0">
	<tbody>
		<tr>
			<td>
			<p>1</p>

			<p>2</p>

			<p>3</p>
			</td>
			<td>
			<p><code>rows </code><code>=</code> <code>list</code><code>(session.execute(</code><code>"SELECT * FROM t"</code><code>))</code></p>

			<p><code>assert</code> <code>rows[</code><code>0</code><code>] </code><code>=</code><code>=</code> <code>1</code> <code># Do not do this.</code></p>

			<p><code>assert</code> <code>rows[</code><code>1</code><code>] </code><code>=</code><code>=</code> <code>2</code></p>
			</td>
		</tr>
	</tbody>
</table>

<p>There’s no need to check for errors in C* logs, as that is automatically handled for you by dtest’s teardown.</p>

<p>Once you have finished with your test, make sure your new code is compliant with PEP8. See&nbsp;<a href="https://github.com/riptano/cassandra-dtest/blob/master/CONTRIBUTING.md">contributing.md</a>&nbsp;for how to do so, along with further style guidelines. Now just open a pull request against the riptano/cassandra-dtest repository, and we’ll be happy to review and merge it.</p>


Build and scale cloud native apps

Discover the benefits of DBaaS and why your apps deserve an upgrade.

Learn about NoSQL Databases

Learn about NoSQL databases with Apache Cassandra and Astra DB.

2022 Recap: A Year for Customers, Community, and Real-Time Data

Highlights from 2022 and a glimpse into the year ahead.

ViewingTechnical How To’s

How to Write a Dtest

Sign up for our Developer Newsletter