diff --git a/ctdb/tests/README b/ctdb/tests/README index 5b6b714560f..87c7db397e0 100644 --- a/ctdb/tests/README +++ b/ctdb/tests/README @@ -1,106 +1,87 @@ Introduction ------------ -The run_tests script can be run as follows: +For a developer, the simplest way of running most tests on a local +machine from within the git repository is: - scripts/run_tests simple/*.sh + make test -It can also be run from other places (e.g. the top level ctdb source -directory), as it works out where the tree is. +This runs all unit tests (onnode, takeover, tool, eventscripts) and +the tests against local daemons (simple) using the script +tests/run_tests.sh. -The pseudo-test simple/00_ctdb_init.sh causes ctdb to be (re)started -on all nodes to attempt to force the cluster into a healthy state. By -default (i.e. if CTDB_TEST_REAL_CLUSTER is unset - see below) this -causes some local daemons to be started on the local machine. Tests -can also be run against a real or virtual cluster. All tests -communicate with cluster nodes using onnode - when using local daemons -this is accomplished via some test hooks in onnode and the ctdb -client. +When running tests against a real or virtual cluster the script +tests/run_cluster_tests.sh can be used. This runs all integration +tests (simple, complex). -Command-line options --------------------- +Both of these scripts can also take a list of tests to run. -The most useful option is "-s", which causes a summary of test results -to be printed at the end of testing. +scripts/run_tests +----------------- -Environment variables ---------------------- +The above scripts invoke tests/scripts/run_tests. This script has a +lot of command-line switches. Some of the more useful options +include: -run_tests supports several environment variables, mostly implemented -in scripts/ctdb_test_env. These are: + -s Print a summary of tests results after running all tests -* CTDB_TEST_REAL_CLUSTER + -l Use local daemons for integration tests - If set, testing will occur on a real or virtual cluster. + This allows the tests in "simple" to be run against local + daemons. - Assumptions: + All integration tests communicate with cluster nodes using + onnode or the ctdb tool, which both have some test hooks to + support local daemons. - - The ctdb client command can be found via $PATH on the nodes. + By default 3 daemons are used. If you want to use a different + number of daemons then do not use this option but set + TEST_LOCAL_DAEMONS to the desired number of daemons instead. + The -l option just sets TEST_LOCAL_DAEMONS to 3... :-) - - Password-less ssh access to the cluster nodes is permitted from - the test host. + -e Exit on the first test failure - - $CTDB_NODES_FILE is set to the location of a file similar to - /etc/ctdb/nodes. The file can be obtained by scping it from one - of the cluster nodes. + -H No headers - for running single test with other wrapper - - See CTDB_TEST_REMOTE_DIR. + This allows tests to be embedded in some other test framework + and executed one-by-one with all the required + environment/infrastructure. - If not set, testing will proceed against local daemons. + This replaces the old ctdb_test_env script. -* CTDB_TEST_REMOTE_DIR +How do the tests find remote test programs? +------------------------------------------- - This may be required when running against a real or virtual cluster - (as opposed to local daemons). +If the all of the cluster nodes have the CTDB git tree in the same +location as on the test client then no special action is necessary. +The simplest way of doing this is to share the tree to cluster nodes +and test clients via NFS. - If set, this points to a directory containing the contents of the - tests/scripts/ directory, as well as all of the test binaries. This - can be accomplished in a couple of ways: +If cluster nodes do not have the CTDB git tree then +CTDB_TEST_REMOTE_DIR can be set to a directory that, on each cluster +node, contains the contents of tests/scripts/ and tests/bin/. - * By copying the relevant scripts/binaries to some directory. +In the future this will hopefully (also) be supported via a ctdb-test +package. - * Building an RPM containing all of the test code that is required - on the cluster nodes and installing it on each node. Hopefully - this will be supported in a future version of the CTDB packaging - process. +Running the ctdb tool under valgrind +------------------------------------ - If not set, the test system assumes that the CTDB tree is available - in the same location on the cluster nodes as on the test host. This - could be accomplished by copying or by sharing with NFS (or - similar). +The easiest way of doing this is something like: -* VALGRIND + VALGRIND="valgrind -q" scripts/run_tests ... - This can be used to cause all invocations of the ctdb client (and, - with local daemons, the ctdbd daemons themselves) to occur under - valgrind. +This can be used to cause all invocations of the ctdb client (and, +with local daemons, the ctdbd daemons themselves) to occur under +valgrind. - The easiest way of doing this is something like: +NOTE: Some libc calls seem to do weird things and perhaps cause +spurious output from ctdbd at start time. Please read valgrind output +carefully before reporting bugs. :-) - VALGRIND="valgrind -q" scripts/run_tests ... +How is the ctdb tool invoked? +----------------------------- - NOTE: Some libc calls seem to do weird things and perhaps cause - spurious output from ctdbd at start time. Please read valgrind - output carefully before reporting bugs. :-) - -* CTDB - - How to invoke the ctdb client. If not already set and if $VALGRIND - is set, this is set to "$VALGRIND ctdb". If this is not already set - but $VALGRIND is not set, this is simply set to "ctdb" - -Look, no run_test! ------------------- - -If you want to integrate individual tests into some other test -environment you can use scripts/ctdb_test_env to wrap individual -tests. They will return 0 on success, non-zero otherwise, and will -print the output omitting the test header/footer that surrounds test -output when tests are run using run_tests. So, you can do something -like: - - for i in simple/*.sh ; do - my_test_framework_wrapper scripts/ctdb_test_env $i - done - -to have your own framework process the test results and output. +$CTDB determines how to invoke the ctdb client. If not already set +and if $VALGRIND is set, this is set to "$VALGRIND ctdb". If this is +not already set but $VALGRIND is not set, this is simply set to "ctdb" diff --git a/ctdb/tests/complex/README b/ctdb/tests/complex/README new file mode 100644 index 00000000000..72de39656af --- /dev/null +++ b/ctdb/tests/complex/README @@ -0,0 +1,2 @@ +Complex integration tests. These need a real or virtual cluster. +That is, they can not be run against local daemons. diff --git a/ctdb/tests/eventscripts/README b/ctdb/tests/eventscripts/README index 33bea9edb6d..266c530bad0 100644 --- a/ctdb/tests/eventscripts/README +++ b/ctdb/tests/eventscripts/README @@ -3,41 +3,45 @@ eventscript unit tests This directory contains some eventscript unit tests for CTDB. These tests can be run as a non-privileged user. There are a lot of stub -implementations of commands (located in bin/) used to make the +implementations of commands (located in stubs/) used to make the eventscripts think they're running against a real system. +Test case filenames look like: + + ..NNN.sh + +The test helper functions will run with specified +options. If using the simple_test() or iterate_test() helper +functions then the 1st argument is automatically passed. When +simple_test_event() is used the event name must be explicitly passed +as the 1st argument - this is more flexible and supports multiple +events per test. + Examples: -* ./run_tests.sh +* ../run_tests.sh . Run all tests, displaying minimal output. -* ./run_tests.sh -s +* ../run_tests.sh -s . Run all tests, displaying minimal output and a summary. -* ./run_tests.sh -s simple/*.sh +* ../run_tests.sh -s ./10.interface.*.sh - Run all the tests in the simple/ subdirectory. + Run all the tests against the 10.interface eventscript. -* ./run_tests.sh -v -s +* ../run_tests.sh -v -s . Run all tests, displaying extra output and a summary. -* ./run_tests.sh -sq +* ../run_tests.sh -sq . Run all tests, displaying only a summary. -* EVENTSCRIPTS_TESTS_TRACE="sh -x" \ - ./run_tests.sh simple/10.interface.startup.002.sh +* ../run_tests.sh -X ./10.interface.startup.002.sh Run a test and have the eventscript itself run with "sh -x". This will usually make a test fail because the (undesirable) trace output will be included with the output of the eventscript. However, this - is useful for finding out why a test might be failing. You can just - drop the "-x" (minimal command-line editing) to see if changes have - made a test pass. - -The simple/ subdirectory contains tests that exercise only a single -eventscript. Another directory containing tests that exercise -interactions between eventscripts is coming soon... :-) + is useful for finding out why a test might be failing. diff --git a/ctdb/tests/onnode/README b/ctdb/tests/onnode/README index 58943d3845f..162faae0211 100644 --- a/ctdb/tests/onnode/README +++ b/ctdb/tests/onnode/README @@ -3,31 +3,31 @@ onnode unit tests Examples: -* ./run_tests.sh +* ../run_tests.sh . Run all tests, displaying output. -* ./run_tests.sh -s +* ../run_tests.sh -s . Run all tests, displaying output and a summary. -* ./run_tests.sh -sq +* ../run_tests.sh -sq . Run all tests, displaying only a summary. -* ONNODE=onnode-buggy-001 ./run_tests.sh -s +* ONNODE=onnode-buggy-001 ../run_tests.sh -s . Run against stubs/onnode-buggy-001 instead of default onnode version. Add more buggy versions of onnode to this directory as bugs are fixed to enable test validation using this feature. -* ./run_tests.sh ./009*.sh +* ../run_tests.sh ./009*.sh Run only the specified tests. -* ONNODE="bash -x stubs/onnode-buggy-001" ./run_tests.sh ./0090.sh - ONNODE="bash -x ../../tools/onnode" ./run_tests.sh ./0090.sh +* ONNODE="bash -x stubs/onnode-buggy-001" ../run_tests.sh ./0090.sh + ONNODE="bash -x ../../tools/onnode" ../run_tests.sh ./0090.sh Debug the specified test or test failure. The test will fail because the bash trace output will be included in the test output. diff --git a/ctdb/tests/simple/README b/ctdb/tests/simple/README new file mode 100644 index 00000000000..3ac738dc6ce --- /dev/null +++ b/ctdb/tests/simple/README @@ -0,0 +1,2 @@ +Simple integration tests. These can be run against a pool of CTDB +daemons running on the local machine - aka "local daemons". diff --git a/ctdb/tests/takeover/README b/ctdb/tests/takeover/README new file mode 100644 index 00000000000..764f389a04a --- /dev/null +++ b/ctdb/tests/takeover/README @@ -0,0 +1,5 @@ +Unit tests for the CTDB IP allocation algorithm(s). + +Test case filenames look like .NNN.sh, where +indicates the IP allocation algorithm to use. These use the +ctdb_takeover_test test program. diff --git a/ctdb/tests/tool/README b/ctdb/tests/tool/README new file mode 100644 index 00000000000..d4a4a347dac --- /dev/null +++ b/ctdb/tests/tool/README @@ -0,0 +1,19 @@ +Unit tests for the ctdb tool (i.e. tools/ctdb). + +Test case filenames can take 2 forms: + +* func..NNN.sh + + Run in the ctdb tool code using the + ctdb_tool_libctdb test program. This test program uses test stubs + for libctdb functions. + +* stubby..NNN.sh + + Run the ctdb_tool_stubby test program with as the 1st + argument - subsequent are passed to simple_test(). ctdb_tool_stubby + is linked against the test stubs for libctdb functions. + +To add tests here you may need to change commands/functions in the +ctdb tool so that they use libctdb. You will also need to add the +appropriate test stubs.