ctdb/tests/README

   1 Introduction
   2 ------------
   3
   4 The run_tests script can be run as follows:
   5
   6   scripts/run_tests simple/*.sh
   7
   8 It can also be run from other places (e.g. the top level ctdb source
   9 directory), as it works out where the tree is.
  10
  11 The pseudo-test simple/00_ctdb_init.sh causes ctdb to be (re)started
  12 on all nodes to attempt to force the cluster into a healthy state.  By
  13 default (i.e. if CTDB_TEST_REAL_CLUSTER is unset - see below) this
  14 causes some local daemons to be started on the local machine.  Tests
  15 can also be run against a real or virtual cluster.  All tests
  16 communicate with cluster nodes using onnode - when using local daemons
  17 this is accomplished via some test hooks in onnode and the ctdb
  18 client.
  19
  20 Command-line options
  21 --------------------
  22
  23 The most useful option is "-s", which causes a summary of test results
  24 to be printed at the end of testing.
  25
  26 Environment variables
  27 ---------------------
  28
  29 run_tests supports several environment variables, mostly implemented
  30 in scripts/ctdb_test_env.  These are:
  31
  32 * CTDB_TEST_REAL_CLUSTER
  33
  34   If set, testing will occur on a real or virtual cluster.
  35
  36   Assumptions:
  37
  38   - The ctdb client command can be found via $PATH on the nodes.
  39
  40   - Password-less ssh access to the cluster nodes is permitted from
  41     the test host.
  42
  43   - $CTDB_NODES_FILE is set to the location of a file similar to
  44     /etc/ctdb/nodes.  The file can be obtained by scping it from one
  45     of the cluster nodes.
  46
  47   - See CTDB_TEST_REMOTE_DIR.
  48
  49   If not set, testing will proceed against local daemons.
  50
  51 * CTDB_TEST_REMOTE_DIR
  52
  53   This may be required when running against a real or virtual cluster
  54   (as opposed to local daemons).
  55
  56   If set, this points to a directory containing the contents of the
  57   tests/scripts/ directory, as well as all of the test binaries.  This
  58   can be accomplished in a couple of ways:
  59
  60   * By copying the relevant scripts/binaries to some directory.
  61
  62   * Building an RPM containing all of the test code that is required
  63     on the cluster nodes and installing it on each node.  Hopefully
  64     this will be supported in a future version of the CTDB packaging
  65     process.
  66
  67   If not set, the test system assumes that the CTDB tree is available
  68   in the same location on the cluster nodes as on the test host.  This
  69   could be accomplished by copying or by sharing with NFS (or
  70   similar).
  71
  72 * VALGRIND
  73
  74   This can be used to cause all invocations of the ctdb client (and,
  75   with local daemons, the ctdbd daemons themselves) to occur under
  76   valgrind.
  77
  78   The easiest way of doing this is something like:
  79
  80     VALGRIND="valgrind -q" scripts/run_tests ...
  81
  82   NOTE: Some libc calls seem to do weird things and perhaps cause
  83   spurious output from ctdbd at start time.  Please read valgrind
  84   output carefully before reporting bugs.  :-)
  85
  86 * CTDB
  87
  88   How to invoke the ctdb client.  If not already set and if $VALGRIND
  89   is set, this is set to "$VALGRIND ctdb".  If this is not already set
  90   but $VALGRIND is not set, this is simply set to "ctdb"
  91
  92 Look, no run_test!
  93 ------------------
  94
  95 If you want to integrate individual tests into some other test
  96 environment you can use scripts/ctdb_test_env to wrap individual
  97 tests.  They will return 0 on success, non-zero otherwise, and will
  98 print the output omitting the test header/footer that surrounds test
  99 output when tests are run using run_tests.  So, you can do something
 100 like:
 101
 102   for i in simple/*.sh ; do
 103       my_test_framework_wrapper scripts/ctdb_test_env $i
 104   done
 105
 106 to have your own framework process the test results and output.