This is an automated email from the ASF dual-hosted git repository.
bereng pushed a commit to branch cassandra-3.11
in repository https://gitbox.apache.org/repos/asf/cassandra.git
commit 317a4a864c2c3bdb1d82f97d0c0d724f11e7efe2
Merge: 1e42c10 fdabda1
Author: Bereng <berenguerbl...@gmail.com>
AuthorDate: Tue May 18 06:38:10 2021 +0200
Merge branch 'cassandra-3.0' into cassandra-3.11
doc/source/development/testing.rst | 5 +
.../org/apache/cassandra/RepeatableRunner.java | 109 +++++++++++++++++++++
2 files changed, 114 insertions(+)
diff --cc doc/source/development/testing.rst
index 0f91629,0000000..2ec1631
mode 100644,000000..100644
--- a/doc/source/development/testing.rst
+++ b/doc/source/development/testing.rst
@@@ -1,134 -1,0 +1,139 @@@
+.. Licensed to the Apache Software Foundation (ASF) under one
+.. or more contributor license agreements. See the NOTICE file
+.. distributed with this work for additional information
+.. regarding copyright ownership. The ASF licenses this file
+.. to you under the Apache License, Version 2.0 (the
+.. "License"); you may not use this file except in compliance
+.. with the License. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+
+.. highlight:: none
+
+Testing
+*******
+
+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.
+
+
+Unit Testing
+============
+
+The most simple way to test code in Cassandra is probably by writing a unit
test. Cassandra uses JUnit as a testing framework and test cases can be found
in the ``test/unit`` directory. Ideally you’d be able to create a unit test for
your implementation that would exclusively cover the class you created (the
unit under test). Unfortunately this is not always possible and Cassandra
doesn’t have a very mock friendly code base. Often you’ll find yourself in a
situation where you have to ma [...]
+
+.. code-block:: 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)));
+ }
+
+Unit tests can be run from the command line using the ``ant test`` command,
``ant test -Dtest.name=<simple_classname>`` to execute a test suite or ``ant
testsome -Dtest.name=<FQCN> -Dtest.methods=<testmethod1>[,testmethod2]`` for
individual tests. For example, to run all test methods in the
``org.apache.cassandra.cql3.SimpleQueryTest`` class, you would run::
+
+ ant test -Dtest.name=SimpleQueryTest
+
+To run only the ``testStaticCompactTables()`` test method from that class,
you would run::
+
+ ant testsome -Dtest.name=org.apache.cassandra.cql3.SimpleQueryTest
-Dtest.methods=testStaticCompactTables
+
+Long running tests
+------------------
+
+Test that consume a significant amount of time during execution can be found
in the ``test/long`` directory and executed as a regular JUnit test or
standalone program. Except for the execution time, there’s nothing really
special about them. However, ant will execute tests under ``test/long`` only
when using the ``ant long-test`` target.
+
++Flaky tests
++-----------
++
++If a test failure is difficult to reproduce you can always use a shell loop,
circle repeat strategy and similar solutions. At the JUnit level
``RepeatableRunner`` will let you run a JUnit class N times for convenience. On
tests that are fast this is a much faster way to iterate than doing it at the
shell level. Beware of tests that modify singleton state or similar as they
won't work.
++
+DTests
+======
+
+One way of doing integration or system testing at larger scale is by using
`dtest <https://github.com/riptano/cassandra-dtest>`_, which stands for
“Cassandra Distributed Tests”. The idea is to automatically setup Cassandra
clusters using various configurations and simulate certain use cases you want
to test. This is done using Python scripts and ``ccmlib`` from the `ccm
<https://github.com/pcmanus/ccm>`_ project. Dtests will setup clusters using
this library just as you do running ad-ho [...]
+
+Using dtests helps us to prevent regression bugs by continually executing
tests on the `CI server <http://cassci.datastax.com/>`_ against new patches.
For frequent contributors, this Jenkins is set up to build branches from their
GitHub repositories. It is likely that your reviewer will use this Jenkins
instance to run tests for your patch. Read more on the motivation behind the CI
server `here
<http://www.datastax.com/dev/blog/cassandra-testing-improvements-for-developer-convenience-an
[...]
+
+The best way to learn how to write dtests is probably by reading the
introduction "`How to Write a Dtest
<http://www.datastax.com/dev/blog/how-to-write-a-dtest>`_" and by looking at
existing, recently updated tests in the project. New tests must follow certain
`style conventions
<https://github.com/apache/cassandra-dtest/blob/trunk/CONTRIBUTING.md>`_ that
are being checked before accepting contributions. In contrast to Cassandra,
dtest issues and pull-requests are managed on github, the [...]
+
+Creating a good dtest can be tough, but it should not prevent you from
submitting patches! Please ask in the corresponding JIRA ticket how to write a
good dtest for the patch. In most cases a reviewer or committer will able to
support you, and in some cases they may offer to write a dtest for you.
+
+Performance Testing
+===================
+
+Performance tests for Cassandra are a special breed of tests that are not
part of the usual patch contribution process. In fact you can contribute tons
of patches to Cassandra without ever running performance tests. They are
important however when working on performance improvements, as such
improvements must be measurable.
+
+Cassandra Stress Tool
+---------------------
+
+TODO: `CASSANDRA-12365
<https://issues.apache.org/jira/browse/CASSANDRA-12365>`_
+
+cstar_perf
+----------
+
+Another tool available on github is `cstar_perf
<https://github.com/datastax/cstar_perf>`_ that can be used for intensive
performance testing in large clusters or locally. Please refer to the project
page on how to set it up and how to use it.
+
+CircleCI
+========
+
+Cassandra ships with a default `CircleCI <https://circleci.com>`_
configuration, to enable running tests on your branches, you need to go the
CircleCI website, click "Login" and log in with your github account. Then you
need to give CircleCI permission to watch your repositories. Once you have done
that, you can optionally configure CircleCI to run tests in parallel - click
"Projects", then your github account and then click the settings for the
project. If you leave the parallelism at [...]
+
+The configuration for CircleCI is in the ``.circleci/config.yml`` file. This
configuration file is meant to use low resources, you can find equivalent
configuration files using more resources in the same ``.circleci`` directory.
Please read the ``readme.md`` file in that directory for further information.
Note that the higher resources are not available in the free tier of CircleCI.
+
+The optional ``repeated_utest``/``repeated_dtest`` CircleCI jobs run a
specific JUnit/Python test repeatedly. This is useful to verify that a certain
test is stable. It's usually a good idea to run these jobs when adding or
modifying a test. To specify what test should be run and the number of
repetitions you should edit the related evironment variables in the CircleCI
configuration file:
+
++------------------------------------+------------------------------------------------------------------+
+| Variable | Description
|
++====================================+==================================================================+
+| ``REPEATED_UTEST_TARGET`` | The Ant test target to run, for
example: |
+| |
|
+| | * ``testsome``
|
+| | * ``test-jvm-dtest-some``
|
+| | * ``test-cdc``
|
+| | * ``test-compression``
|
+| | * ``test-system-keyspace-directory``
|
++------------------------------------+------------------------------------------------------------------+
+| ``REPEATED_UTEST_CLASS`` | The name of the Java test class to be
run multiple times, for |
+| | example:
|
+| |
|
+| | *
``Rorg.apache.cassandra.cql3.ViewTest`` |
+| | *
``Rorg.apache.cassandra.distributed.test.PagingTest`` |
++------------------------------------+------------------------------------------------------------------+
+| ``REPEATED_UTEST_METHODS`` | The optional specific methods within
``REPEATED_UTEST_CLASS`` to |
+| | be run, for example:
|
+| |
|
+| | * ``testCompoundPartitionKey``
|
+| | *
``testCompoundPartitionKey,testStaticTable`` |
++------------------------------------+------------------------------------------------------------------+
+| ``REPEATED_UTEST_COUNT`` | The number of times that the repeated
Java test should be run |
++------------------------------------+------------------------------------------------------------------+
+| ``REPEATED_UTEST_STOP_ON_FAILURE`` | Whether the utest iteration should
stop on the first failure |
++------------------------------------+------------------------------------------------------------------+
+| ``REPEATED_DTEST_NAME`` | The Python dtest to be run multiple
times, for example: |
+| |
|
+| | * ``cqlsh_tests/test_cqlsh.py``
|
+| | *
``cqlsh_tests/test_cqlsh.py::TestCqlshSmoke`` |
+| | *
``cqlsh_tests/test_cqlsh.py::TestCqlshSmoke::test_insert`` |
++------------------------------------+------------------------------------------------------------------+
+| ``REPEATED_DTEST_VNODES`` | Whether the repeated Python dtest
should use vnodes |
++------------------------------------+------------------------------------------------------------------+
+| ``REPEATED_DTEST_COUNT`` | The number of times that the repeated
Python dtest should be run |
++------------------------------------+------------------------------------------------------------------+
+| ``REPEATED_DTEST_STOP_ON_FAILURE`` | Whether the dtest iteration should
stop on the first failure |
++------------------------------------+------------------------------------------------------------------+
+
+
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@cassandra.apache.org
For additional commands, e-mail: commits-h...@cassandra.apache.org
