| <!DOCTYPE html> |
| <html lang="en"> |
| <head> |
| <meta charset="utf-8"> |
| <meta name="viewport" content="width=device-width,initial-scale=1.0"> |
| <title>Apache Cassandra | Apache Cassandra Documentation</title> |
| <link rel="stylesheet" href="../../assets/css/site.css"> |
| <link rel="schema.dcterms" href="https://purl.org/dc/terms/"> |
| <meta name="dcterms.subject" content="_"> |
| <meta name="dcterms.identifier" content="master"> |
| <meta name="generator" content="Antora 2.3.4"> |
| <link rel="icon" href="../../assets/img/favicon.ico" type="image/x-icon"> |
| <script> |
| const script = document.createElement("script"); |
| const domain = window.location.hostname; |
| script.type = "text/javascript"; |
| script.src = "https://plausible.cassandra.apache.org/js/plausible.js"; |
| script.setAttribute("data-domain",domain); |
| script.setAttribute("defer",'true'); |
| script.setAttribute("async",'true'); |
| document.getElementsByTagName("head")[0].appendChild(script); |
| </script> </head> |
| <body class="basic "> |
| <div class="container mx-auto relative"> |
| <script src="https://ajax.googleapis.com/ajax/libs/jquery/3.6.0/jquery.min.js"></script> |
| <meta property="og:type" content="website" /> |
| <meta property="og:url" content="/" /> |
| <meta property="og:site_name" content="Apache Cassandra" /> |
| |
| <header id="top-nav"> |
| <div class="inner relative"> |
| <div class="header-social-icons text-right"> |
| <a href="https://twitter.com/cassandra?lang=en" target="_blank" styles="margin-left: 20px;"><img src="../../assets/img/twitter-icon-circle-white.svg" alt="twitter icon" width="24"></a> |
| <a href="https://www.linkedin.com/company/apache-cassandra/" target="_blank" styles="margin-left: 20px;"><img src="../../assets/img/LI-In-Bug.png" alt="linked-in icon" width="24"></a> |
| <a href="https://www.youtube.com/c/PlanetCassandra" target="_blank" styles="margin-left: 20px;"><img src="../../assets/img/youtube-icon.png" alt="youtube icon" width="24"></a> |
| </div> |
| <div class="cf"> |
| <div class="logo left"><a href="/"><img src="../../assets/img/logo-white-r.png" alt="cassandra logo"></a></div> |
| <div class="mobile-nav-icon right"> |
| <img class="toggle-icon" src="../../assets/img/hamburger-nav.svg"> |
| </div> |
| <ul class="main-nav nav-links right flex flex-vert-center flex-space-between"> |
| <li> |
| <a class="nav-link hide-mobile">Get Started</a> |
| <ul class="sub-menu bg-white"> |
| <li class="pa-micro"> |
| <a href="/_/cassandra-basics.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-basics.png" alt="cassandra basics icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Cassandra Basics |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/quickstart.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-rocket.png" alt="cassandra basics icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Quickstart |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/ecosystem.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-ecosystem.png" alt="cassandra basics icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Ecosystem |
| </div> |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a class="nav-link" href="/doc/latest/">Documentation</a></li> |
| <li> |
| <a class="nav-link" href="/_/community.html">Community</a> |
| <ul class="sub-menu bg-white"> |
| <li class="pa-micro"> |
| <a href="/_/community.html#code-of-conduct"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-welcome.png" alt="welcome icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Welcome |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/community.html#discussions"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-discussions.png" alt="discussions icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Discussions |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/community.html#project-governance"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-governance.png" alt="Governance icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Governance |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/community.html#how-to-contribute"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-contribute.png" alt="Contribute icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Contribute |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/community.html#meet-the-community"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-community.png" alt="Meet the Community icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Meet the Community |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/cassandra-catalyst-program.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-catalyst.png" alt="Catalyst icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Catalyst Program |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro hide-mobile"> |
| <a href="/_/events.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-events.png" alt="Events icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Events |
| </div> |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li> |
| <a class="nav-link hide-mobile">Learn</a> |
| <ul class="sub-menu bg-white"> |
| <li class="pa-micro"> |
| <a href="/_/Apache-Cassandra-5.0-Moving-Toward-an-AI-Driven-Future.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-basics.png" alt="Basics icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Cassandra 5.0 |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/case-studies.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-case-study.png" alt="Case Studies icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Case Studies |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/resources.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-resources.png" alt="Resources icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Resources |
| </div> |
| </a> |
| </li> |
| <li class="pa-micro"> |
| <a href="/_/blog.html"> |
| <div class="sub-nav-icon"> |
| <img src="../../assets/img/sub-menu-blog.png" alt="Blog icon"> |
| </div> |
| <div class="sub-nav-text teal py-small"> |
| Blog |
| </div> |
| </a> |
| </li> |
| </ul> |
| </li> |
| <li><a class="nav-link btn btn--filled" href="/_/download.html">Download Now</a></li> |
| </ul> |
| </div> |
| </div> |
| </header> |
| |
| <div class="hero hero--home grad"> |
| <div class="eye"></div> |
| <div id="home-content" class="text-center flex flex-center flex-column relative z2 ma-xlarge"> |
| <h1>Testing</h1> |
| </div> |
| </div> |
| <div class="flex-center py-large arrow"> |
| <div class="inner inner--narrow"> |
| <div id="preamble"> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Creating tests is one of the most important and also most difficult |
| parts of developing Cassandra. There are different ways to test your |
| code depending on what you’re working on.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Cassandra tests can be divided into three main categories, based on the |
| way how they are executed:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong><a href="#java_tests">Java tests</a></strong> - tests implemented in Java and being a part of the |
| Cassandra project. You can distinguish the following subcategories there:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><strong><a href="#junit_tests">JUnit tests</a></strong> - consists of unit tests, single-node integration |
| tests and some tool tests; those tests may run a server with limited |
| functionality in the same JVM as the test code</p> |
| </li> |
| <li> |
| <p><strong><a href="#jvm_distributed_tests">JVM distributed tests</a></strong> - integrated tests against one or multiple |
| nodes, each running in their own classloader; also contains upgrade |
| tests</p> |
| </li> |
| <li> |
| <p><strong><a href="#microbenchmarks">Micro-benchmarks</a></strong> - micro-benchmarks implemented with |
| <a href="https://github.com/openjdk/jmh">JMH framework</a></p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| <li> |
| <p><strong><a href="#cqlsh_tests">CQLSH tests</a></strong> - CQLSH tests are Python tests written with the Nose |
| test framework. They verify the CQLSH client that can be found in the |
| bin directory. They aim at verifying CQLSH specific behavior like output |
| formatting, autocompletion, parsing, etc).</p> |
| </li> |
| <li> |
| <p><strong><a href="#python_dtests">Python distributed tests</a></strong> - Python distributed tests are |
| implemented on top of the PyTest framework and located outside the main |
| Cassandra project in the separate repository |
| <a href="https://github.com/apache/cassandra-dtest">apache/cassandra-dtest</a>. They |
| test Cassandra via <a href="https://github.com/riptano/ccm">CCM</a> verifying |
| operation results, logs, and cluster state. Python Distributed tests are |
| Cassandra version agnostic. They include upgrade tests.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>In case you want to run DTests with your own version of CCM, please refer to requirements.txt in |
| <a href="https://github.com/apache/cassandra-dtest">apache/cassandra-dtest</a> how to do it.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The recipes for running those tests can be found in the cassandra-builds repository <a href="https://github.com/apache/cassandra-builds/tree/trunk/build-scripts">here</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Running full test suites locally takes hours, if not days. Beyond running specific tests you know are applicable, or are failing, to the work at hand, it is recommended to rely upon the project’s <a href="/_/development/ci.html">Continuous Integration systems</a>. If you are not a committer, and don’t have access to a premium CircleCI plan, ask one of the committers to test your patch on the project’s <a href="https://ci-cassandra.apache.org/">ci-cassandra.apache.org</a>.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="java_tests"><a class="anchor" href="#java_tests"></a>Java tests</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The simplest test to write for Cassandra code is a unit test. Cassandra |
| uses JUnit as a testing framework and test cases can be found in the |
| <code>test/unit</code> directory. Ideally, you’ll create a unit test for |
| your implementation that exclusively covers the class you created |
| (the unit under test).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Unfortunately, this is not always possible, because Cassandra doesn’t |
| have a very mock friendly code base. Often you’ll find yourself in a |
| situation where you have to use the embedded Cassandra instance to |
| interact with your test. If you want to use CQL in your test, |
| you can extend CQLTester and use some convenient helper methods, as |
| shown here:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-java hljs" data-lang="java">@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))); |
| }</code></pre> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="junit_tests"><a class="anchor" href="#junit_tests"></a>JUnit tests</h3> |
| <div class="paragraph"> |
| <p>To run the unit tests:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-none hljs" data-lang="none">ant test</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>However, this is probably not what you want to do, since that |
| command would run all the unit tests (those from <code>test/unit</code>). It would |
| take about an hour or more to finish.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To run the specific test class or even a method, use the following |
| command:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-none hljs" data-lang="none">ant testsome -Dtest.name=<TestClassName> -Dtest.methods=<testMethodName></code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>test.name</code> property is for either a simple or fully qualified class |
| name</p> |
| </li> |
| <li> |
| <p><code>test.methods</code> property is optional; if not specified, all test cases |
| from the specified class are executed. Though, you can also specify |
| multiple methods separating them by comma</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>You can also use the IDE to run the tests - when you generate IDE files and |
| properly import the Cassandra project, you can run the |
| tests by right-clicking on the test class or package name. Remember that |
| it is not enough to compile with IDE for some tests, and you need to |
| call <code>ant jar</code> to build the distribution artifacts. When |
| the test runs some tool as an external process, the tool expects |
| Cassandra artifacts to be in the build directory.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that those commands apply to the tests in the <code>test/unit</code> |
| directory. There are, however, some other test categories that have |
| tests in individual directories:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>test/burn</code> - to run them, call <code>ant test-burn</code> or |
| <code>ant burn-testsome</code>; |
| <code>ant burn-test-jar</code> builds a self-contained jar for e.g. remote execution; not currently |
| used for running burn tests in our scripts. <code>ant burn-test-jar</code> exists only on 4.0+ branches</p> |
| </li> |
| <li> |
| <p><code>test/long</code> - to run them, call <code>ant long-test</code> or <code>ant long-testsome</code></p> |
| </li> |
| <li> |
| <p><code>test/memory</code> - to run them, call <code>ant test-memory</code></p> |
| </li> |
| <li> |
| <p><code>test/microbench</code> discussed in <a href="#microbenchmarks">Micro-benchmarks</a></p> |
| </li> |
| <li> |
| <p><code>test/distributed</code> discussed in <a href="#jvm_distributed_tests">JVM distributed tests</a></p> |
| </li> |
| </ul> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-tip" title="Tip"></i> |
| </td> |
| <td class="content"> |
| <div class="title">Hint</div> |
| <div class="paragraph"> |
| <p>If you get the error similar to the one below, install the |
| <code>ant-optional</code> package |
| because you need the <code>JUnitTask</code> class |
| (see <a href="ide.html" class="page">prerequisites</a>).</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-none hljs" data-lang="none">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]</code></pre> |
| </div> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="stress_and_fqltool_tests"><a class="anchor" href="#stress_and_fqltool_tests"></a>Stress and FQLTool tests</h3> |
| <div class="paragraph"> |
| <p><em>Stress</em> and <em>FQLTool</em> are separate modules located under the <code>tools</code> |
| directory in the Cassandra project. They have their own source code and |
| unit tests. To run the tests for those tools, first, build jar artifacts |
| for them by calling:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-asciidoc hljs" data-lang="asciidoc">ant fqltool-build fqltool-build-test |
| ant stress-build stress-build-test</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Then you can execute the tests with either one of the commands:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">ant fqltool-test |
| ant stress-test |
| and stress-test-some</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>or using your IDE.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="jvm_distributed_tests"><a class="anchor" href="#jvm_distributed_tests"></a>JVM distributed tests</h3> |
| <div class="paragraph"> |
| <p>JVM distributed tests can run a cluster of nodes inside a single JVM - |
| they utilize a particular framework (that can be found at |
| <a href="https://github.com/apache/cassandra-in-jvm-dtest-api">apache/cassandra-in-jvm-dtest-api</a>) |
| for that purpose. Those tests are intended to test features that require |
| more started nodes or verify specific behaviors when the nodes get |
| restarted, including upgrading them from one version to another. The |
| tests are located at the <code>test/distributed</code> directory of the Cassandra |
| project; however, only <code>org.apache.cassandra.distributed.test</code> and |
| <code>org.apache.cassandra.upgrade</code> packages contain the actual tests. The |
| rest of the files are various utilities related to the distributed test |
| framework.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The distributed tests can be run in few ways. <code>ant test-jvm-dtest</code> |
| command runs all the distributed JVM tests. It is not very useful; thus, |
| there is also <code>ant test-jvm-dtest-some</code>, which allows specifying test |
| class and test name in the similar way as you could do that for the |
| <code>ant testsome</code> command, for example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">ant test-jvm-dtest-some -Dtest.name=org.apache.cassandra.distributed.test.SchemaTest |
| |
| ant test-jvm-dtest-some -Dtest.name=org.apache.cassandra.distributed.test.SchemaTest -Dtest.methods=readRepair</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-tip" title="Tip"></i> |
| </td> |
| <td class="content"> |
| <div class="title">Hint</div> |
| <div class="paragraph"> |
| <p>Unlike for JUnit tests, for JVM distributed tests you need to provide |
| fully qualified class name</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>Distributed tests can also be run using IDE (in fact, you can even debug |
| them).</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="upgrade-tests"><a class="anchor" href="#upgrade-tests"></a>Upgrade tests</h4> |
| <div class="paragraph"> |
| <p>JVM upgrade tests can be run precisely in the same way as any other JVM |
| distributed tests. However, running them requires some preparation - |
| for example, if a test verifies the upgrade from Cassandra 3.0 and |
| Cassandra 3.11 to the current version (say Cassandra 4.0), you need to |
| have prepared dtest uber JARs for all involved versions. To do this:</p> |
| </div> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Check out Cassandra 3.0 based branch you want to test the upgrade |
| from into some other directory</p> |
| </li> |
| <li> |
| <p>Build dtest uber JAR with <code>ant dtest-jar</code> command</p> |
| </li> |
| <li> |
| <p>Copy the created <code>build/dtest-3.0.x.jar</code> to the build |
| directory of your target Cassandra project</p> |
| </li> |
| <li> |
| <p>Repeat the procedure for Cassandra 3.11</p> |
| </li> |
| <li> |
| <p>Once you have dtest jars of all the involved versions for the upgrade |
| test, you can finally execute the test using your favorite method, say:</p> |
| </li> |
| </ol> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">ant test-jvm-dtest-some -Dtest.name=org.apache.cassandra.distributed.upgrade.MixedModeReadTest</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-tip" title="Tip"></i> |
| </td> |
| <td class="content"> |
| <div class="title">Hint</div> |
| <div class="paragraph"> |
| <p>You may pre-generate dtest uber JARs for certain past Cassandra |
| releases, store is somewhere and reuse in you future work - no need to |
| rebuild them all the time.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="running-multiple-tests"><a class="anchor" href="#running-multiple-tests"></a>Running multiple tests</h3> |
| <div class="paragraph"> |
| <p>It is possible to define a list of test classes to run with a single command. |
| Define a text file, by default called <code>testlist.txt</code>, and put it into your project directory. |
| Here is an example of that file:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-none hljs" data-lang="none">org/apache/cassandra/db/ReadCommandTest.java |
| org/apache/cassandra/db/ReadCommandVerbHandlerTest.java</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Essentially, you list the paths to the class files of the tests you want |
| to run. Then you call <code>ant testclasslist</code>, which uses the text file |
| to run the listed tests. Note that, by default, it applies to |
| the tests under the <code>test/unit</code> directory and takes the <code>testlist.txt</code> |
| file, but this behavior can be modified by providing additional |
| parameters:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">ant testclasslist -Dtest.classlistprefix=<category> -Dtest.classlistfile=<class list file></code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For example, if you want to run the distributed tests this way, and say |
| our tests were listed in the <code>distributed-tests-set.txt</code> file (paths to |
| test classes relative to <code>test/distributed</code> directory), you can do that |
| by calling:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">ant testclasslist -Dtest.classlistprefix=distributed -Dtest.classlistfile=distributed-tests-set.txt</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="running-coverage-analysis"><a class="anchor" href="#running-coverage-analysis"></a>Running coverage analysis</h3> |
| <div class="paragraph"> |
| <p>Coverage reports from the executed JVM tests can be obtained in two ways |
| - through IDE - for example, IntelliJ supports running tests with |
| coverage analysis (another run button next to the one for running in debug mode).</p> |
| </div> |
| <div class="paragraph"> |
| <p>The other way is to run Ant target <code>codecoverage</code>. Basically, it works |
| for all the ways mentioned above of running JVM tests - the only |
| difference is that instead of specifying the target directly, you pass it |
| as a property called <code>taskname</code>. For example - given the original test |
| command is:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">ant testsome -Dtest.name=org.apache.cassandra.utils.concurrent.AccumulatorTest</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>to run it with coverage analysis, do:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">ant codecoverage -Dtaskname=testsome -Dtest.name=org.apache.cassandra.utils.concurrent.AccumulatorTest</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>It applies to all the targets like <code>test</code>, <code>testsome</code>, <code>test-long</code>, |
| etc., even <code>testclasslist</code>. You can find the coverage report in |
| <code>build/jacoco</code> (<code>index.html</code> is the entry point for the HTML version, |
| but there are also XML and CSV reports).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Note that if you run various tests that way, the coverage information is |
| added to the previously collected runs. That is, you get the cumulative |
| coverage from all runs unless you clean up the project or at least clean |
| up the recorded coverage information by executing the command |
| <code>ant jacoco-cleanup</code>.</p> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="microbenchmarks"><a class="anchor" href="#microbenchmarks"></a>Micro-benchmarks</h3> |
| <div class="paragraph"> |
| <p>To run micro-benchmarks, first build the uber jar for the JMH framework. |
| Use the following <code>ant</code> command:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">ant build-jmh</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Then, you can run either all benchmarks (from the <code>test/microbench</code> |
| directory) or the tests matching the name specified by the |
| <code>benchmark.name</code> property when executing the <code>ant microbench</code> command. |
| Whether you run all benchmarks or just a selected one, only classes |
| under the <code>microbench</code> package are selected. The class selection pattern |
| is actually <code>.*microbench.*${benchmark.name}</code>. For example, |
| in order to run <code>org.apache.cassandra.test.microbench.ChecksumBench</code>, |
| execute:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">ant microbench -Dbenchmark.name=ChecksumBench</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>ant microbench</code> command runs the benchmarks with default parameters |
| as defined in the <code>build.xml</code> file (see the <code>microbench</code> target |
| definition). If you want to run JMH with custom parameters, |
| consider using the <code>test/bin/jmh</code> script. In addition to allowing you to |
| customize JMH options, it also sets up the environment and JVM options |
| by running Cassandra init script (<code>conf/cassandra-env.sh</code>). Therefore, |
| it lets the environment for running the tests to be more similar to |
| the production environment. For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">test/bin/jmh -gc true org.apache.cassandra.test.microbench.CompactionBench.compactTest</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>You may also find it useful to run the command to list all the tests: |
| <code>test/bin/jmh -l</code> or <code>test/bin/jmh -lp</code> (also showing the default |
| parameters). The list of all options can be shown by running |
| <code>test/bin/jmh -h</code></p> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="python-tests"><a class="anchor" href="#python-tests"></a>Python tests</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="docker"><a class="anchor" href="#docker"></a>Docker</h3> |
| <div class="paragraph"> |
| <p>The Docker approach is recommended for running Python distributed tests. |
| The behavior will be more repeatable, matching the same environment as |
| the official testing on <a href="https://ci-cassandra.apache.org/">Cassandra CI</a>.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="setup-docker"><a class="anchor" href="#setup-docker"></a>Setup Docker</h4> |
| <div class="paragraph"> |
| <p>If you are on Linux, you need to install Docker using the system package |
| manager.</p> |
| </div> |
| <div class="paragraph"> |
| <p>If you are on MacOS, you can use either |
| <a href="https://www.docker.com/products/docker-desktop">Docker Desktop</a> or some |
| <a href="https://runnable.com/docker/install-docker-on-macos">other approach</a>.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="pull-the-docker-image"><a class="anchor" href="#pull-the-docker-image"></a>Pull the Docker image</h4> |
| <div class="paragraph"> |
| <p>The Docker image used on the official Cassandra CI can be found in |
| <a href="https://github.com/apache/cassandra-builds">this</a> repository. |
| You can use either |
| <a href="https://github.com/apache/cassandra-builds/blob/trunk/docker/testing/ubuntu2004_j11.docker">docker/testing/ubuntu2004_j11.docker</a> |
| or |
| <a href="https://github.com/apache/cassandra-builds/blob/trunk/docker/testing/ubuntu2004_j11_w_dependencies.docker">docker/testing/ubuntu2004_j11_w_dependencies.docker</a> |
| The second choice has prefetched dependencies for building each main |
| Cassandra branch. Those images can be either built |
| locally (as per instructions in the GitHub repo) or pulled from the |
| Docker Hub - see |
| <a href="https://hub.docker.com/search?q=apache%2Fcassandra-testing&type=image">here</a>.</p> |
| </div> |
| <div class="paragraph"> |
| <p>First, pull the image from Docker Hub (it will either fetch or |
| update the image you previously fetched):</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">docker pull apache/cassandra-testing-ubuntu2004-java11-w-dependencies</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="start-the-container"><a class="anchor" href="#start-the-container"></a>Start the container</h4> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">docker run -di -m 8G --cpus 4 \ |
| --mount type=bind,source=/path/to/cassandra/project,target=/home/cassandra/cassandra \ |
| --mount type=bind,source=/path/to/cassandra-dtest,target=/home/cassandra/cassandra-dtest \ |
| --name test \ |
| apache/cassandra-testing-ubuntu2004-java11-w-dependencies \ |
| dumb-init bash</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-tip" title="Tip"></i> |
| </td> |
| <td class="content"> |
| <div class="title">Hint</div> |
| <div class="paragraph"> |
| <p>Many distributed tests are not that demanding in terms of resources |
| - 4G / 2 cores should be enough to start one node. However, some tests |
| really run multiple nodes, and some of them are automatically skipped |
| if the machine has less than 32G (there is a way to force running them |
| though). Usually 8G / 4 cores is a convenient choice which is enough |
| for most of the tests.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>To log into the container, use the following <code>docker exec</code> command:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">docker exec -it `docker container ls -f name=test -q` bash</code></pre> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="setup_python_env"><a class="anchor" href="#setup_python_env"></a>Setup Python environment</h4> |
| <div class="paragraph"> |
| <p>The tests are implemented in Python, so a Python virtual environment |
| (see <a href="https://docs.python.org/3/tutorial/venv.html">here</a> for details) |
| with all the required dependencies is good to be set up. If you are |
| familiar with the Python ecosystem, you know what it is all about. |
| Otherwise, follow the instructions; it should be enough to run the |
| tests.</p> |
| </div> |
| <div class="paragraph"> |
| <p>For Python distributed tests do:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">cd /home/cassandra/cassandra-dtest |
| virtualenv --python=python3 --clear --always-copy ../dtest-venv |
| source ../dtest-venv/bin/activate |
| CASS_DRIVER_NO_CYTHON=1 pip install -r requirements.txt</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For CQLSH tests, replace some paths:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">cd /home/cassandra/cassandra/pylib |
| virtualenv --python=python3 --clear --always-copy ../../cqlsh-venv |
| source ../../cqlsh-venv/bin/activate |
| CASS_DRIVER_NO_CYTHON=1 pip install -r requirements.txt</code></pre> |
| </div> |
| </div> |
| <div class="admonitionblock tip"> |
| <table> |
| <tr> |
| <td class="icon"> |
| <i class="fa icon-tip" title="Tip"></i> |
| </td> |
| <td class="content"> |
| <div class="title">Hint</div> |
| <div class="paragraph"> |
| <p>You may wonder why this weird environment variable <code>CASS_DRIVER_NO_CYTHON=1</code> was added - it is not required at all. Still, it allows avoiding the compilation of Cassandra driver with Cython, which is not needed unless you want to test that Cython compiled driver. In the end, it speeds up the installation of the requirements significantly from the order of minutes to the order of seconds.</p> |
| </div> |
| </td> |
| </tr> |
| </table> |
| </div> |
| <div class="paragraph"> |
| <p>The above commands are also helpful for importing those test projects |
| into your IDE. In that case, you need to run them on your host |
| system rather than in Docker container. For example, when you open the |
| project in IntelliJ, the Python plugin may ask you to select the runtime |
| environment. In this case, choose the existing <em>virtualenv</em> |
| based environment and point to <code>bin/python</code> under the created |
| <code>dtest-venv</code> directory (or <code>cqlsh-venv</code>, or whichever name you have |
| chosen).</p> |
| </div> |
| <div class="paragraph"> |
| <p>Whether you want to play with Python distributed tests or CQLSH tests, |
| you need to select the right virtual environment. Remember to switch to |
| the one you want:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">deactivate |
| source /home/cassandra/dtest-venv/bin/activate</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>or</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">deactivate |
| source /home/cassandra/cqlsh-venv/bin/activate</code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cqlsh_tests"><a class="anchor" href="#cqlsh_tests"></a>CQLSH tests</h3> |
| <div class="paragraph"> |
| <p>CQLSH tests are located in the <code>pylib/cqlshlib/test</code> directory. They are |
| based on the Nose framework. They require a running Cassandra cluster |
| (it can be one or more nodes cluster) as they start a CQL shell |
| client which tries to connect to a live node. Each test case starts the |
| CQLSH client as a subprocess, issues some commands, and verifies the |
| outcome returned by CQLSH to the console.</p> |
| </div> |
| <div class="paragraph"> |
| <p>You need to set up and activate the <code>virtualenv</code> for CQLSH tests (see |
| <a href="#setup_python_env">Setup Python environment</a> section for details).</p> |
| </div> |
| <div class="paragraph"> |
| <p>So let’s start the cluster first - you can use CCM for that (note that |
| CCM gets automatically installed with the <code>virtualenv</code> and is |
| immediately available once the <code>virtualenv</code> is activated):</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">ccm create test -n 1 --install-dir=/home/cassandra/cassandra |
| ccm updateconf "enable_user_defined_functions: true" |
| ccm updateconf "enable_scripted_user_defined_functions: true" |
| ccm updateconf "cdc_enabled: true" |
| ccm start --wait-for-binary-proto</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>When those commands complete successfully, there is a cluster up and |
| running, and you can run the CQLSH tests. To do so, go to the |
| <code>pylib/cqlshlib</code> directory (not to the test subdirectory) and call |
| the <code>nosetests</code> command without any arguments. The tests take around |
| 5 minutes to complete.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Finally, remember that since you manually started the cluster, you need |
| to stop it manually - just call:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">ccm remove test</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>There is a helper script that does all of those things for you. In |
| particular, it builds the Cassandra project, creates a virtual |
| environment, runs the CCM cluster, executes the tests, and eventually |
| removes the cluster. You find the script in the <code>pylib</code> directory. The |
| only argument it requires is the Cassandra project directory:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">cassandra@b69a382da7cd:~/cassandra/pylib$ ./cassandra-cqlsh-tests.sh /home/cassandra/cassandra</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>As you noticed, if you have already built Cassandra, the previous method |
| of running tests is much faster. Just remember that all the |
| <code>ccm updateconf</code> calls must be aligned with the Cassandra version you |
| are testing, with the supported features enabled. |
| Otherwise, Cassandra won’t start.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="running-selected-tests"><a class="anchor" href="#running-selected-tests"></a>Running selected tests</h4> |
| <div class="paragraph"> |
| <p>You may run all test tests from the selected file by passing that |
| file as an argument:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">~/cassandra/pylib/cqlshlib$ nosetests test/test_constants.py</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>To run a specific test case, you need to specify the module, class name, |
| and the test name, for example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">~/cassandra/pylib/cqlshlib$ nosetests cqlshlib.test.test_cqlsh_output:TestCqlshOutput.test_boolean_output</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>For more information on selecting tests with the Nose framework, see |
| <a href="https://nose.readthedocs.io/en/latest/usage.html">this</a> page.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="python_dtests"><a class="anchor" href="#python_dtests"></a>Python distributed tests</h3> |
| <div class="paragraph"> |
| <p>One way of doing integration or system testing at larger scale is |
| using <a href="https://github.com/apache/cassandra-dtest">dtest</a> (Cassandra distributed test). |
| These dtests automatically setup Cassandra clusters with certain configurations and simulate use cases you want to test.</p> |
| </div> |
| <div class="paragraph"> |
| <p>The best way to learn how to write dtests is probably by reading the |
| introduction "http://www.datastax.com/dev/blog/how-to-write-a-dtest[How |
| to Write a Dtest]". |
| Looking at existing, recently updated tests in the project is another good activity. |
| New tests must follow certain |
| <a href="https://github.com/apache/cassandra-dtest/blob/master/CONTRIBUTING.md">style |
| conventions</a> that are checked before contributions are accepted. |
| In contrast to Cassandra, dtest issues and pull requests are managed on |
| github, therefore you should make sure to link any created dtests in your |
| Cassandra ticket and also refer to the ticket number in your dtest PR.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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.</p> |
| </div> |
| <div class="sect3"> |
| <h4 id="run-the-tests-quick-examples"><a class="anchor" href="#run-the-tests-quick-examples"></a>Run the tests - quick examples</h4> |
| <div class="paragraph"> |
| <p>Note that you need to set up and activate the virtualenv for DTests |
| (see <a href="#setup_python_env">Setup Python environment</a> section for details). Tests are implemented |
| with the PyTest framework, so you use the pytest command to run them. |
| Let’s run some tests:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">pytest --cassandra-dir=/home/cassandra/cassandra schema_metadata_test.py::TestSchemaMetadata::test_clustering_order</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>That command runs the <code>test_clustering_order</code> test case from |
| <code>TestSchemaMetadata</code> class, located in the <code>schema_metadata_test.py</code> |
| file. You may also provide the file and class to run all test cases from |
| that class:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">pytest --cassandra-dir=/home/cassandra/cassandra schema_metadata_test.py::TestSchemaMetadata</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>or just the file name to run all test cases from all classes defined in that file.</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">pytest --cassandra-dir=/home/cassandra/cassandra schema_metadata_test.py</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>You may also specify more individual targets:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">pytest --cassandra-dir=/home/cassandra/cassandra schema_metadata_test.py::TestSchemaMetadata::test_basic_table_datatype schema_metadata_test.py::TestSchemaMetadata::test_udf</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>If you run pytest without specifying any test, it considers running all |
| the tests it can find. More on the test selection |
| <a href="https://docs.pytest.org/en/6.2.x/usage.html#specifying-tests-selecting-tests">here</a> |
| You probably noticed that <code>--cassandra-dir=/home/cassandra/cassandra</code> |
| is constantly added to the command line. It is |
| one of the <code>cassandra-dtest</code> custom arguments - the mandatory one - |
| unless it is defined, you cannot run any Cassandra dtest.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="setting-up-pytest"><a class="anchor" href="#setting-up-pytest"></a>Setting up PyTest</h4> |
| <div class="paragraph"> |
| <p>All the possible options can be listed by invoking pytest <code>--help</code>. You |
| see tons of possible parameters - some of them are native PyTest |
| options, and some come from Cassandra DTest. When you look carefully at |
| the help note, you notice that some commonly used options, usually fixed |
| for all the invocations, can be put into the <code>pytest.ini</code> file. In |
| particular, it is quite practical to define the following:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-none hljs" data-lang="none">cassandra_dir = /home/cassandra/cassandra |
| log_cli = True |
| log_cli_level = DEBUG</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>so that you do not have to provide <code>--cassandra-dir</code> param each time you |
| run a test. The other two options set up console logging - remove them |
| if you want logs stored only in log files.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="running-tests-with-specific-configuration"><a class="anchor" href="#running-tests-with-specific-configuration"></a>Running tests with specific configuration</h4> |
| <div class="paragraph"> |
| <p>There are a couple of options to enforce exact test configuration (their |
| names are quite self-explanatory):</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>--use-vnodes</code></p> |
| </li> |
| <li> |
| <p><code>--num-token=xxx</code> - enables the support of virtual nodes with a certain |
| number of tokens</p> |
| </li> |
| <li> |
| <p><code>--use-off-heap-memtables</code> - use off-heap memtables instead of the |
| default heap-based</p> |
| </li> |
| <li> |
| <p>`--data-dir-count-per-instance=xxx - the number of data directories |
| configured per each instance</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Note that the list can grow in the future as new predefined |
| configurations can be added to dtests. It is also possible to pass extra |
| Java properties to each Cassandra node started by the tests - define |
| those options in the <code>JVM_EXTRA_OPTS</code> environment variable before |
| running the test.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="listing-the-tests"><a class="anchor" href="#listing-the-tests"></a>Listing the tests</h4> |
| <div class="paragraph"> |
| <p>You can do a dry run, so that the tests are only listed and not |
| invoked. To do that, add <code>--collect-only</code> to the pytest command. |
| That additional <code>-q</code> option will print the results in the same |
| format as you would pass the test name to the pytest command:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">pytest --collect-only -q</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>lists all the tests pytest would run if no particular test is specified. |
| Similarly, to list test cases in some class, do:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">$ pytest --collect-only -q schema_metadata_test.py::TestSchemaMetadata |
| schema_metadata_test.py::TestSchemaMetadata::test_creating_and_dropping_keyspace |
| schema_metadata_test.py::TestSchemaMetadata::test_creating_and_dropping_table |
| schema_metadata_test.py::TestSchemaMetadata::test_creating_and_dropping_table_with_2ary_indexes |
| schema_metadata_test.py::TestSchemaMetadata::test_creating_and_dropping_user_types |
| schema_metadata_test.py::TestSchemaMetadata::test_creating_and_dropping_udf |
| schema_metadata_test.py::TestSchemaMetadata::test_creating_and_dropping_uda |
| schema_metadata_test.py::TestSchemaMetadata::test_basic_table_datatype |
| schema_metadata_test.py::TestSchemaMetadata::test_collection_table_datatype |
| schema_metadata_test.py::TestSchemaMetadata::test_clustering_order |
| schema_metadata_test.py::TestSchemaMetadata::test_compact_storage |
| schema_metadata_test.py::TestSchemaMetadata::test_compact_storage_composite |
| schema_metadata_test.py::TestSchemaMetadata::test_nondefault_table_settings |
| schema_metadata_test.py::TestSchemaMetadata::test_indexes |
| schema_metadata_test.py::TestSchemaMetadata::test_durable_writes |
| schema_metadata_test.py::TestSchemaMetadata::test_static_column |
| schema_metadata_test.py::TestSchemaMetadata::test_udt_table |
| schema_metadata_test.py::TestSchemaMetadata::test_udf |
| schema_metadata_test.py::TestSchemaMetadata::test_uda</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>You can copy/paste the selected test case to the pytest command to |
| run it.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="filtering-tests"><a class="anchor" href="#filtering-tests"></a>Filtering tests</h4> |
| <div class="sect4"> |
| <h5 id="based-on-configuration"><a class="anchor" href="#based-on-configuration"></a>Based on configuration</h5> |
| <div class="paragraph"> |
| <p>Most tests run with any configuration, but a subset of tests (test |
| cases) only run if a specific configuration is used. In particular, |
| there are tests annotated with:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>@pytest.mark.vnodes</code> - the test is only invoked when the support of |
| virtual nodes is enabled</p> |
| </li> |
| <li> |
| <p><code>@pytest.mark.no_vnodes</code> - the test is only invoked when the support |
| of virtual nodes is disabled</p> |
| </li> |
| <li> |
| <p><code>@pytest.mark.no_offheap_memtables</code> - the test is only invoked if |
| off-heap memtables are not used</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Note that enabling or disabling <em>vnodes</em> is obviously mutually |
| exclusive. If a test is marked to run only with <em>vnodes</em>, it does not |
| run when <em>vnodes</em> is disabled; similarly, when a test is marked to run |
| only without <em>vnodes</em>, it does not run when <em>vnodes</em> is enabled - |
| therefore, there are always some tests which would not run with a single |
| configuration.</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="based-on-resource-usage"><a class="anchor" href="#based-on-resource-usage"></a>Based on resource usage</h5> |
| <div class="paragraph"> |
| <p>There are also tests marked with:</p> |
| </div> |
| <div class="paragraph"> |
| <p><code>@pytest.mark.resource_intensive</code></p> |
| </div> |
| <div class="paragraph"> |
| <p>which means that the test requires more resources than a regular test |
| because it usually starts a cluster of several nodes. The meaning of |
| resource-intensive is hardcoded to 32GB of available memory, and unless |
| your machine or docker container has at least that amount of RAM, such |
| test is skipped. There are a couple of arguments that allow for some |
| control of that automatic exclusion:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>--force-resource-intensive-tests</code> - forces the execution of tests |
| marked as <code>resource_intensive</code>, regardless of whether there is enough |
| memory available or not</p> |
| </li> |
| <li> |
| <p><code>--only-resource-intensive-tests</code> - only run tests marked as |
| <code>resource_intensive</code> - it makes all the tests without |
| <code>resource_intensive</code> annotation to be filtered out; technically, it is |
| equivalent to passing native PyTest argument: <code>-m resource_intensive</code></p> |
| </li> |
| <li> |
| <p><code>--skip-resource-intensive-tests</code> - skip all tests marked as |
| <code>resource_intensive</code> - it is the opposite argument to the previous one, |
| and it is equivalent to the PyTest native argument: <code>-m 'not resource_intensive'</code></p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="based-on-the-test-type"><a class="anchor" href="#based-on-the-test-type"></a>Based on the test type</h5> |
| <div class="paragraph"> |
| <p>Upgrade tests are marked with:</p> |
| </div> |
| <div class="paragraph"> |
| <p><code>@pytest.mark.upgrade_test</code></p> |
| </div> |
| <div class="paragraph"> |
| <p>Those tests are not invoked by default at all (just like running |
| PyTest with <code>-m 'not upgrade_test'</code>), and you have to add some extra |
| options to run them: |
| * <code>--execute-upgrade-tests</code> - enables execution of upgrade tests along |
| with other tests - when this option is added, the upgrade tests are not |
| filtered out |
| * <code>--execute-upgrade-tests-only</code> - execute only upgrade tests and filter |
| out all other tests which do not have <code>@pytest.mark.upgrade_test</code> |
| annotation (just like running PyTest with <code>-m 'upgrade_test'</code>)</p> |
| </div> |
| </div> |
| <div class="sect4"> |
| <h5 id="filtering-examples"><a class="anchor" href="#filtering-examples"></a>Filtering examples</h5> |
| <div class="paragraph"> |
| <p>It does not matter whether you want to invoke individual tests or all |
| tests or whether you only want to list them; the above filtering rules |
| apply. So by using <code>--collect-only</code> option, you can learn which tests |
| would be invoked.</p> |
| </div> |
| <div class="paragraph"> |
| <p>To list all the applicable tests for the current configuration, use the |
| following command:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">pytest --collect-only -q --execute-upgrade-tests --force-resource-intensive-tests</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>List tests specific to vnodes (which would only run if vnodes are enabled):</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">pytest --collect-only -q --execute-upgrade-tests --force-resource-intensive-tests --use-vnodes -m vnodes</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>List tests that are not resource-intensive</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">pytest --collect-only -q --execute-upgrade-tests --skip-resource-intensive-tests</code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="upgrade-tests-2"><a class="anchor" href="#upgrade-tests-2"></a>Upgrade tests</h4> |
| <div class="paragraph"> |
| <p>Upgrade tests always involve more than one product version. There are |
| two kinds of upgrade tests regarding the product versions they span - |
| let’s call them fixed and generated.</p> |
| </div> |
| <div class="paragraph"> |
| <p>In case of fixed tests, the origin and target versions are hardcoded. |
| They look pretty usual, for example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">pytest --collect-only -q --execute-upgrade-tests --execute-upgrade-tests-only upgrade_tests/upgrade_supercolumns_test.py</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>prints:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">upgrade_tests/upgrade_supercolumns_test.py::TestSCUpgrade::test_upgrade_super_columns_through_all_versions |
| upgrade_tests/upgrade_supercolumns_test.py::TestSCUpgrade::test_upgrade_super_columns_through_limited_versions</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>When you look into the code, you will see the fixed upgrade path:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-python hljs" data-lang="python">def test_upgrade_super_columns_through_all_versions(self): |
| self._upgrade_super_columns_through_versions_test(upgrade_path=[indev_2_2_x, indev_3_0_x, indev_3_11_x, indev_trunk])</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The generated upgrade tests are listed several times - the first |
| occurrence of the test case is a generic test definition, and then |
| it is repeated many times in generated test classes. For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">pytest --cassandra-dir=/home/cassandra/cassandra --collect-only -q --execute-upgrade-tests --execute-upgrade-tests-only upgrade_tests/cql_tests.py -k test_set</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>prints:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">upgrade_tests/cql_tests.py::cls::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes3RF3_Upgrade_current_2_2_x_To_indev_2_2_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes3RF3_Upgrade_current_3_0_x_To_indev_3_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes3RF3_Upgrade_current_3_11_x_To_indev_3_11_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes3RF3_Upgrade_current_4_0_x_To_indev_4_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes3RF3_Upgrade_indev_2_2_x_To_indev_3_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes3RF3_Upgrade_indev_2_2_x_To_indev_3_11_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes3RF3_Upgrade_indev_3_0_x_To_indev_3_11_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes3RF3_Upgrade_indev_3_0_x_To_indev_4_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes3RF3_Upgrade_indev_3_11_x_To_indev_4_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes3RF3_Upgrade_indev_4_0_x_To_indev_trunk::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes2RF1_Upgrade_current_2_2_x_To_indev_2_2_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes2RF1_Upgrade_current_3_0_x_To_indev_3_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes2RF1_Upgrade_current_3_11_x_To_indev_3_11_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes2RF1_Upgrade_current_4_0_x_To_indev_4_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes2RF1_Upgrade_indev_2_2_x_To_indev_3_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes2RF1_Upgrade_indev_2_2_x_To_indev_3_11_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes2RF1_Upgrade_indev_3_0_x_To_indev_3_11_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes2RF1_Upgrade_indev_3_0_x_To_indev_4_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes2RF1_Upgrade_indev_3_11_x_To_indev_4_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes2RF1_Upgrade_indev_4_0_x_To_indev_trunk::test_set</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>In this example, the test case name is just <code>test_set</code>, and the class |
| name is <code>TestCQL</code> - the suffix of the class name is automatically |
| generated from the provided specification. The first component is the |
| cluster specification - there are two variants: <code>Nodes2RF1</code> and <code>Nodes3RF3</code> |
| - they denote that the upgrade is tested on 2 nodes cluster with a |
| keyspace using replication factor = 1. Analogously the second variant |
| uses 3 nodes cluster with RF = 3.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Then, there is the upgrade specification - for example, |
| <code>Upgrade_indev_3_11_x_To_indev_4_0_x</code> - which means that this test |
| upgrades from the development version of Cassandra 3.11 to the |
| development version of Cassandra 4.0 - the meaning of <code>indev/current</code> |
| and where they are defined is explained later.</p> |
| </div> |
| <div class="paragraph"> |
| <p>When you look into the implementation, you notice that such upgrade test |
| classes inherit from <code>UpgradeTester</code> class, and they have the |
| specifications defined at the end of the file. In this particular case, |
| it is something like:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-python hljs" data-lang="python">topology_specs = [ |
| {'NODES': 3, |
| 'RF': 3, |
| 'CL': ConsistencyLevel.ALL}, |
| {'NODES': 2, |
| 'RF': 1}, |
| ] |
| specs = [dict(s, UPGRADE_PATH=p, __test__=True) |
| for s, p in itertools.product(topology_specs, build_upgrade_pairs())]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>As you can see, there is a list of the cluster specifications and |
| the cross product is calculated with upgrade paths returned by the |
| <code>build_upgrade_pairs()</code> function. That list of specifications is used to |
| dynamically generate upgrade tests.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Suppose you need to test something specifically for your scenario. In |
| that case, you can add more cluster specifications, like a test with 1 |
| node or a test with 5 nodes with some different replication factor or |
| consistency level. The <code>build_upgrade_pairs()</code> returns the list of |
| upgrade paths (actually just the origin and target version). That list |
| is generated according to the upgrade manifest.</p> |
| </div> |
| <div class="sect4"> |
| <h5 id="upgrade-manifest"><a class="anchor" href="#upgrade-manifest"></a>Upgrade manifest</h5> |
| <div class="paragraph"> |
| <p>The upgrade manifest is a file where all the upgrade paths are defined. |
| It is a regular Python file located at |
| <code>upgrade_tests/upgrade_manifest.py</code>. |
| As you noticed, Cassandra origin and target version descriptions |
| mentioned in the upgrade test consist of <code>indev</code> or <code>current</code> prefix |
| followed by version string. The definitions of each such version |
| description can be found in the manifest, for example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-python hljs" data-lang="python">indev_3_11_x = VersionMeta(name='indev_3_11_x', family=CASSANDRA_3_11, variant='indev', version='github:apache/cassandra-3.11', min_proto_v=3, max_proto_v=4, java_versions=(8,)) |
| |
| current_3_11_x = VersionMeta(name='current_3_11_x', family=CASSANDRA_3_11, variant='current', version='3.11.10', min_proto_v=3, max_proto_v=4, java_versions=(8,))</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>There are a couple of different properties which describe those two |
| versions:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>name</code> - is a name as you can see in the names of the generated |
| test classes</p> |
| </li> |
| <li> |
| <p><code>family</code> - families is an enumeration defined in the beginning of |
| the upgrade manifest - say family <code>CASSANDRA_3_11</code> is just a string |
| <code>"3.11"</code>. Some major features were introduced or removed with new |
| version families, and therefore some checks can be done or some features |
| can be enabled/disabled according to that, for example:</p> |
| </li> |
| </ul> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-python hljs" data-lang="python">if self.cluster.version() < CASSANDRA_4_0: |
| node1.nodetool("enablethrift")</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>But it is also used to determine whether our checked-out version matches |
| the target version in the upgrade pair (more on that later)</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>variant</code> and <code>version</code> - there are <code>indev</code> or <code>current</code> variants:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>indev</code> variant means that the development version of Cassandra |
| will be used. That is, that version is checked out from the Git |
| repository and built before running the upgrade (CCM does it). In this |
| case, the version string is specified as <code>github:apache/cassandra-3.11</code>, |
| which means that it will checkout the <code>cassandra-3.11</code> branch from the |
| GitHub repository whose alias is <code>apache</code>. Aliases are defined in CCM |
| configuration file, usually located at <code>~/.ccm/config</code> - in this |
| particular case, it could be something like:</p> |
| </li> |
| </ul> |
| </div> |
| </li> |
| </ul> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-none hljs" data-lang="none">[aliases] |
| apache:git@github.com:apache/cassandra.git</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>current</code> variant means that a released version of Cassandra will |
| be used. It means that Cassandra distribution denoted by the specified |
| version (3.11.10 in this case) is downloaded from the Apache |
| repository/mirror - again, the repository can be defined in CCM |
| configuration file, under repositories section, something like:</p> |
| </li> |
| </ul> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-none hljs" data-lang="none">[repositories] |
| cassandra=https://archive.apache.org/dist/cassandra</code></pre> |
| </div> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>min_proto_v</code>, <code>max_proto_v</code> - the range of usable Cassandra driver |
| protocol versions</p> |
| </li> |
| <li> |
| <p><code>java_versions</code> - supported Java versions</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>The possible upgrade paths are defined later in the upgrade manifest - |
| when you scroll the file, you will find the <code>MANIFEST</code> map which may |
| look similar to:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-python hljs" data-lang="python">MANIFEST = { |
| current_2_1_x: [indev_2_2_x, indev_3_0_x, indev_3_11_x], |
| current_2_2_x: [indev_2_2_x, indev_3_0_x, indev_3_11_x], |
| current_3_0_x: [indev_3_0_x, indev_3_11_x, indev_4_0_x], |
| current_3_11_x: [indev_3_11_x, indev_4_0_x], |
| current_4_0_x: [indev_4_0_x, indev_trunk], |
| |
| indev_2_2_x: [indev_3_0_x, indev_3_11_x], |
| indev_3_0_x: [indev_3_11_x, indev_4_0_x], |
| indev_3_11_x: [indev_4_0_x], |
| indev_4_0_x: [indev_trunk] |
| }</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>It is a simple map where for the origin version (as a key), there is |
| a list of possible target versions (as a value). Say:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-python hljs" data-lang="python">current_4_0_x: [indev_4_0_x, indev_trunk]</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>means that upgrades from <code>current_4_0_x</code> to |
| <code>indev_4_0_x</code> and from <code>current_4_0_x</code> to <code>indev_trunk</code> will be considered. |
| You may make changes to that upgrade scenario in your development branch |
| according to your needs. |
| There is a command-line option that allows filtering across upgrade |
| scenarios: <code>--upgrade-version-selection=xxx</code>. The possible values for |
| that options are as follows:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>indev</code> - which is the default, only selects those upgrade scenarios |
| where the target version is in <code>indev</code> variant</p> |
| </li> |
| <li> |
| <p><code>both</code> - selects upgrade paths where either both origin and target |
| versions are in the same variant or have the same version family</p> |
| </li> |
| <li> |
| <p><code>releases</code> - selects upgrade paths between versions in current variant |
| or from the <code>current</code> to <code>indev</code> variant if both have the same version |
| family</p> |
| </li> |
| <li> |
| <p><code>all</code> - no filtering at all - all variants are tested</p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="running-upgrades-with-local-distribution"><a class="anchor" href="#running-upgrades-with-local-distribution"></a>Running upgrades with local distribution</h4> |
| <div class="paragraph"> |
| <p>The upgrade test can use your local Cassandra distribution, the one |
| specified by the <code>cassandra_dir</code> property, as the target version if the |
| following preconditions are satisfied:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>the target version is in the <code>indev</code> variant,</p> |
| </li> |
| <li> |
| <p>the version family set in the version description matches the version |
| family of your local distribution</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>For example, your local distribution is branched off from the |
| <code>cassandra-4.0</code> branch, likely matching <code>indev_4_0_x</code>. It means that the |
| upgrade path with target version <code>indev_4_0_x</code> uses your local |
| distribution. |
| There is a handy command line option which will filter out all the |
| upgrade tests which do not match the local distribution: |
| <code>--upgrade-target-version-only</code>. Given you are on <code>cassandra-4.0</code> branch, |
| when applied to the previous example, it will be something similar to:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">pytest --cassandra-dir=/home/cassandra/cassandra --collect-only -q --execute-upgrade-tests --execute-upgrade-tests-only upgrade_tests/cql_tests.py -k test_set --upgrade-target-version-only</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>prints:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">upgrade_tests/cql_tests.py::cls::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes3RF3_Upgrade_current_4_0_x_To_indev_4_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes3RF3_Upgrade_indev_3_0_x_To_indev_4_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes3RF3_Upgrade_indev_3_11_x_To_indev_4_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes2RF1_Upgrade_current_4_0_x_To_indev_4_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes2RF1_Upgrade_indev_3_0_x_To_indev_4_0_x::test_set |
| upgrade_tests/cql_tests.py::TestCQLNodes2RF1_Upgrade_indev_3_11_x_To_indev_4_0_x::test_set</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>You can see that the upgrade tests were limited to the ones whose target |
| version is <code>indev</code> and family matches 4.0.</p> |
| </div> |
| </div> |
| <div class="sect3"> |
| <h4 id="logging"><a class="anchor" href="#logging"></a>Logging</h4> |
| <div class="paragraph"> |
| <p>A couple of common PyTest arguments control what is logged to the file |
| and the console from the Python test code. Those arguments which start |
| from <code>--log-xxx</code> are pretty well described in the help message |
| (<code>pytest --help</code>) and in PyTest documentation, so it will not be discussed |
| further. However, most of the tests start with the cluster of |
| Cassandra nodes, and each node generates its own logging information and |
| has its own data directories.</p> |
| </div> |
| <div class="paragraph"> |
| <p>By default the logs from the nodes are copied to the unique directory |
| created under logs subdirectory under root of dtest project. For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">(venv) cassandra@b69a382da7cd:~/cassandra-dtest$ ls logs/ -1 |
| 1627455923457_test_set |
| 1627456019264_test_set |
| 1627456474949_test_set |
| 1627456527540_test_list |
| last</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>The <code>last</code> item is a symbolic link to the directory containing the logs |
| from the last executed test. Each such directory includes logs from each |
| started node - system, debug, GC as well as standard streams registered |
| upon each time the node was started:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">(venv) cassandra@b69a382da7cd:~/cassandra-dtest$ ls logs/last -1 |
| node1.log |
| node1_debug.log |
| node1_gc.log |
| node1_startup-1627456480.3398306-stderr.log |
| node1_startup-1627456480.3398306-stdout.log |
| node1_startup-1627456507.2186499-stderr.log |
| node1_startup-1627456507.2186499-stdout.log |
| node2.log |
| node2_debug.log |
| node2_gc.log |
| node2_startup-1627456481.10463-stderr.log |
| node2_startup-1627456481.10463-stdout.log</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>Those log files are not collected if <code>--delete-logs</code> command-line option |
| is added to PyTest. The nodes also produce data files which may be |
| sometimes useful to examine to resolve some failures. Those files are |
| usually deleted when the test is completed, but there are some options |
| to control that behavior:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>--keep-test-dir</code> - keep the whole CCM directory with data files and |
| logs when the test completes</p> |
| </li> |
| <li> |
| <p><code>--keep-failed-test-dir</code> – only keep that directory when the test has |
| failed</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>Now, how to find where is that directory for the certain test - you need |
| to grab that information from the test logs - for example, you may add |
| <code>-s</code> option to the command line and then look for <code>"dtest_setup INFO"</code> |
| messages. For example:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plain hljs" data-lang="plain">05:56:06,383 dtest_setup INFO cluster ccm directory: /tmp/dtest-0onwvgkr</code></pre> |
| </div> |
| </div> |
| <div class="paragraph"> |
| <p>says that the cluster work directory is <code>/tmp/dtest-0onwvgkr</code>, and all |
| node directories can be found under the <code>test</code> subdirectory:</p> |
| </div> |
| <div class="listingblock"> |
| <div class="content"> |
| <pre class="highlightjs highlight"><code class="language-plaintext hljs" data-lang="plaintext">(venv) cassandra@b69a382da7cd:~/cassandra-dtest$ ls /tmp/dtest-0onwvgkr/test -1 |
| cluster.conf |
| node1 |
| node2</code></pre> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="performance-testing"><a class="anchor" href="#performance-testing"></a>Performance Testing</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Performance tests for Cassandra are a special breed of tests that are |
| not part of the usual patch contribution process. In fact, many people |
| contribute a lot of patches to Cassandra without ever running performance |
| tests. However, they are important when working on performance |
| improvements; such improvements must be measurable.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Several tools exist for running performance tests. Here are a few to investigate:</p> |
| </div> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p>Described above <a href="#microbenchmarks">Micro-benchmarks</a></p> |
| </li> |
| <li> |
| <p><code>cassandra-stress</code>: built-in Cassandra stress tool</p> |
| </li> |
| <li> |
| <p><a href="https://github.com/thelastpickle/tlp-stress">tlp-stress</a></p> |
| </li> |
| <li> |
| <p><a href="https://github.com/nosqlbench/nosqlbench">NoSQLBench</a></p> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| </div> |
| <footer class="grad grad--two flex-center pb-xlarge"> |
| <div class="inner text-center z2 relative"> |
| <h2 class="white py-small">Get started with Cassandra, fast.</h2> |
| <a id="footer-cta" href="/_/quickstart.html" class="btn btn--filled ma-medium">Quickstart Guide</a> |
| </div> |
| <div class="inner flex flex-distribute-items mt-xlarge z2 relative"> |
| <div class="col-2"> |
| <div id="footer-logo" class="logo logo--footer mb-medium"><img src="../../assets/img/logo-white-r.png" alt="Cassandra Logo"></div> |
| <p>Apache Cassandra<img src="../../assets/img/registered.svg" alt="®" style="width:18px;"> powers mission-critical deployments with improved performance and unparalleled levels of scale in the cloud.</p> |
| <div class="footer-social-icons"> |
| <a href="https://twitter.com/cassandra?lang=en" target="_blank"><img src="../../assets/img/twitter-icon-circle-white.svg" alt="twitter icon" width="24"></a> |
| <a href="https://www.linkedin.com/company/apache-cassandra/" target="_blank"><img src="../../assets/img/LI-In-Bug.png" alt="linked-in icon" width="24"></a> |
| <a href="https://www.youtube.com/c/PlanetCassandra" target="_blank"><img src="../../assets/img/youtube-icon.png" alt="youtube icon" width="24"></a> |
| </div> |
| </div> |
| <div class="col-2 flex flex-center"> |
| <ul class="columns-2"> |
| <li class="mb-small"><a href="/">Home</a></li> |
| <li class="mb-small"><a href="/_/cassandra-basics.html">Cassandra Basics</a></li> |
| <li class="mb-small"><a href="/_/quickstart.html">Quickstart</a></li> |
| <li class="mb-small"><a href="/_/ecosystem.html">Ecosystem</a></li> |
| <li class="mb-small"><a href="/doc/latest/">Documentation</a></li> |
| <li class="mb-small"><a href="/_/community.html">Community</a></li> |
| <li class="mb-small"><a href="/_/case-studies.html">Case Studies</a></li> |
| <li class="mb-small"><a href="/_/resources.html">Resources</a></li> |
| <li class="mb-small"><a href="/_/blog.html">Blog</a></li> |
| </ul> |
| </div> |
| </div> |
| </footer> |
| <div class="lower-footer bg-white pa-medium"> |
| <div class="flex flex-row flex-vert-center"> |
| <div class="pr-medium"><img src="../../assets/img//feather-small.png" alt="ASF" width="20"></div> |
| <div class="pr-medium"><a href="http://www.apache.org/" target="_blank">Foundation</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/events/current-event.html" target="_blank">Events</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/licenses/" target="_blank">License</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/foundation/thanks" target="_blank">Thanks</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/security" target="_blank">Security</a></div> |
| <div class="pr-medium"><a href="https://privacy.apache.org/policies/privacy-policy-public.html" target="_blank">Privacy</a></div> |
| <div class="pr-medium"><a href="https://www.apache.org/foundation/sponsorship" target="_blank">Sponsorship</a></div> |
| </div> |
| <p class="my-medium">© 2009-<script>document.write(new Date().getFullYear())</script> <a href="https://apache.org" target="_blank">The Apache Software Foundation</a> under the terms of the Apache License 2.0. Apache, the Apache feather logo, Apache Cassandra, Cassandra, and the Cassandra logo, are either registered trademarks or trademarks of The Apache Software Foundation.</p> |
| </div> |
| <div id="fade" class="hidden"></div> |
| <div id="modal" class="hidden"> |
| <div id="close-modal" class="cursor-pointer"><svg viewBox="0 0 24 24" width="24" height="24" stroke="currentColor" stroke-width="2" fill="none" stroke-linecap="round" stroke-linejoin="round" class="css-i6dzq1"><line x1="18" y1="6" x2="6" y2="18"></line><line x1="6" y1="6" x2="18" y2="18"></line></svg></div> |
| <div id="mod-content" class="vid-mod-content resp-container"></div> |
| </div> |
| <script> |
| jQuery(function(){ |
| var windowW = $(window).width(); |
| $(document) |
| .on('click','.mobile-nav-icon',function(){ |
| $('.main-nav').fadeIn(); |
| }) |
| .on('click','.main-nav',function(){ |
| if(windowW <= 1000){ |
| $(this).fadeOut(); |
| } |
| }) |
| .on('click','#version-toggle',function(){ |
| $(this).toggleClass('active'); |
| $(this).next().fadeToggle(); |
| }) |
| .on('click','#mobile-docs-nav-burger', function(){ |
| $(this).toggleClass('active'); |
| $('.docs-nav').toggleClass('active'); |
| }); |
| var url = window.location.pathname; |
| var isQuickstart = url.includes('quickstart.html'); |
| if(isQuickstart){ |
| var footerCTA = document.getElementById('footer-cta'); |
| footerCTA.innerHTML = 'Get latest updates'; |
| footerCTA.setAttribute('href', '/_/blog.html'); |
| } |
| }); |
| </script> |
| </div> |
| </body> |
| <script> |
| jQuery(function(){ |
| jQuery(document) |
| .on('click','.cassandra-cloud h3',function(){ |
| var el = jQuery(this); |
| el.toggleClass('active'); |
| el.next().slideToggle(); |
| }) |
| .on('click','.image-expand img', function(){ |
| $(this).clone().appendTo('#mod-content'); |
| $('#fade,#modal,#close-modal').fadeIn(); |
| $('body,html').addClass('no-scroll'); |
| }) |
| .on('click','#fade,#close-modal', function(){ |
| $('#fade,#modal,#close-modal').fadeOut(); |
| $('body,html').removeClass('no-scroll'); |
| $('#mod-content').html(''); |
| }); |
| }); |
| </script> |
| </html> |