ctdb/tests/README

   1 Introduction
   2 ------------
   3
   4 For a developer, the simplest way of running most tests on a local
   5 machine from within the git repository is:
   6
   7   make test
   8
   9 This runs all unit tests (onnode, takeover, tool, eventscripts) and
  10 the tests against local daemons (simple) using the script
  11 tests/run_tests.sh.
  12
  13 When running tests against a real or virtual cluster the script
  14 tests/run_cluster_tests.sh can be used.  This runs all integration
  15 tests (simple, complex).
  16
  17 Both of these scripts can also take a list of tests to run.  You can
  18 also pass options, which are then passed to run_tests.  However, if
  19 you just try to pass options to run_tests then you lose the default
  20 list of tests that are run.  You can't have everything...
  21
  22 tests/run_tests.sh
  23 ------------------
  24
  25 This script can be used to manually run all or selected unit tests and
  26 simple integration tests against local daemons. Test selection is done
  27 by specifying optional call parameters. If no parameter is given,
  28 all unit tests and simple integration tests are run.
  29
  30 This runs all unit tests of the "tool" category:
  31
  32   ./tests/run_tests.sh tool
  33
  34 In order to run a single test, one simply specifies the path of the
  35 test script to run as the last parameter, e.g.:
  36
  37   ./tests/run_tests.sh ./tests/eventscripts/00.ctdb.monitor.001
  38   ./tests/run_tests.sh ./tests/simple/76_ctdb_pdb_recovery.sh
  39
  40 One can also specify multiple test suites and tests:
  41
  42   ./tests/run_tests.sh eventscripts tool ./tests/onnode/0001.sh
  43
  44 The script also has number of command-line switches.
  45 Some of the more useful options include:
  46
  47   -s  Print a summary of tests results after running all tests
  48
  49   -l  Use local daemons for integration tests
  50
  51       This allows the tests in "simple" to be run against local
  52       daemons.
  53
  54       All integration tests communicate with cluster nodes using
  55       onnode or the ctdb tool, which both have some test hooks to
  56       support local daemons.
  57
  58       By default 3 daemons are used.  If you want to use a different
  59       number of daemons then do not use this option but set
  60       TEST_LOCAL_DAEMONS to the desired number of daemons instead.
  61       The -l option just sets TEST_LOCAL_DAEMONS to 3...  :-)
  62
  63   -e  Exit on the first test failure
  64
  65   -C  Clean up - kill daemons and remove $TEST_VAR_DIR when done
  66
  67       Tests uses a temporary/var directory for test state.  By default,
  68       this directory is not removed when tests are complete, so you
  69       can do forensics or, for integration tests, re-run tests that
  70       have failed against the same directory (with the same local
  71       daemons setup).  So this option cleans things up.
  72
  73       Also kills local daemons associated with directory.
  74
  75   -V  Use <dir> as $TEST_VAR_DIR
  76
  77       Use the specified temporary temporary/var directory.
  78
  79   -H  No headers - for running single test with other wrapper
  80
  81       This allows tests to be embedded in some other test framework
  82       and executed one-by-one with all the required
  83       environment/infrastructure.
  84
  85       This replaces the old ctdb_test_env script.
  86
  87 How do the tests find remote test programs?
  88 -------------------------------------------
  89
  90 If the all of the cluster nodes have the CTDB git tree in the same
  91 location as on the test client then no special action is necessary.
  92 The simplest way of doing this is to share the tree to cluster nodes
  93 and test clients via NFS.
  94
  95 If cluster nodes do not have the CTDB git tree then
  96 CTDB_TEST_REMOTE_DIR can be set to a directory that, on each cluster
  97 node, contains the contents of tests/scripts/ and tests/bin/.
  98
  99 In the future this will hopefully (also) be supported via a ctdb-test
 100 package.
 101
 102 Running the ctdb tool under valgrind
 103 ------------------------------------
 104
 105 The easiest way of doing this is something like:
 106
 107   VALGRIND="valgrind -q" scripts/run_tests ...
 108
 109 This can be used to cause all invocations of the ctdb client (and,
 110 with local daemons, the ctdbd daemons themselves) to occur under
 111 valgrind.
 112
 113 NOTE: Some libc calls seem to do weird things and perhaps cause
 114 spurious output from ctdbd at start time.  Please read valgrind output
 115 carefully before reporting bugs.  :-)
 116
 117 How is the ctdb tool invoked?
 118 -----------------------------
 119
 120 $CTDB determines how to invoke the ctdb client.  If not already set
 121 and if $VALGRIND is set, this is set to "$VALGRIND ctdb".  If this is
 122 not already set but $VALGRIND is not set, this is simply set to "ctdb"
 123
 124 Test and debugging variable options
 125 -----------------------------------
 126
 127        CTDB_TEST_MODE
 128
 129            Set this environment variable to enable test mode.
 130
 131            When testing with multiple local daemons on a single
 132            machine this does 3 things:
 133
 134            * Disables checks related to public IP addresses
 135
 136            * Speeds up the initial recovery during startup at the
 137              expense of some consistency checking
 138
 139            * Disables real-time scheduling