tests: Update README files and add new README files where missing
authorMartin Schwenke <martin@meltin.net>
Fri, 20 Apr 2012 06:37:09 +0000 (16:37 +1000)
committerMartin Schwenke <martin@meltin.net>
Fri, 27 Apr 2012 05:40:43 +0000 (15:40 +1000)
Signed-off-by: Martin Schwenke <martin@meltin.net>
(This used to be ctdb commit bef03b32f8ec114a64c55b25951aeeb939d87b33)

ctdb/tests/complex/README [new file with mode: 0644]
ctdb/tests/simple/README [new file with mode: 0644]
ctdb/tests/takeover/README [new file with mode: 0644]
ctdb/tests/tool/README [new file with mode: 0644]

index 5b6b714560ff616720463accccffa4c0999b4022..87c7db397e0b9c4a24a5f62ba915fb52787d2f56 100644 (file)
-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
-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
+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.
-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
-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
+  -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
+      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.
+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
-  * 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 -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
-  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.  :-)
-  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
-  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 (file)
index 0000000..72de396
--- /dev/null
@@ -0,0 +1,2 @@
+Complex integration tests.  These need a real or virtual cluster.
+That is, they can not be run against local daemons.
index 33bea9edb6d466a6362f3b3407ca007ac4bda814..266c530bad07acea13f3530db45b05fe99544605 100644 (file)
@@ -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:
+  <eventscript>.<event>.NNN.sh
+The test helper functions will run <eventscript> with specified
+options.  If using the simple_test() or iterate_test() helper
+functions then the 1st <event> 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.
-* ./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.
-    ./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.
index 58943d3845f95d10d5e5ab0a1e215615005f7ee5..162faae02110a74e5c145d89dfccb16353aa66cb 100644 (file)
@@ -3,31 +3,31 @@ onnode unit tests
-* ./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 (file)
index 0000000..3ac738d
--- /dev/null
@@ -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 (file)
index 0000000..764f389
--- /dev/null
@@ -0,0 +1,5 @@
+Unit tests for the CTDB IP allocation algorithm(s).
+Test case filenames look like <algorithm>.NNN.sh, where <algorithm>
+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 (file)
index 0000000..d4a4a34
--- /dev/null
@@ -0,0 +1,19 @@
+Unit tests for the ctdb tool (i.e. tools/ctdb).
+Test case filenames can take 2 forms:
+* func.<some_function>.NNN.sh
+  Run <some_function> in the ctdb tool code using the
+  ctdb_tool_libctdb test program.  This test program uses test stubs
+  for libctdb functions.
+* stubby.<command>.NNN.sh
+  Run the ctdb_tool_stubby test program with <command> 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.