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 and INTEGRATION tests.
  10
  11 tests/run_tests.sh
  12 ------------------
  13
  14 This script can be used to manually run all tests or selected tests,
  15 with a variety of options.  For usage, run:
  16
  17   tests/run_tests.sh -h
  18
  19 If no tests are specified this runs all of the UNIT and INTEGRATION
  20 tests.
  21
  22 By default:
  23
  24 * INTEGRATION tests are run against 3 local daemons
  25
  26 * When testing is complete, a summary showing a list is printed
  27   showing the tests run and their results
  28
  29 Tests can be selected in various ways:
  30
  31 * tests/run_tests.sh UNIT INTEGRATION
  32
  33   runs all UNIT and INTEGRATION tests, and is like specifying no tests
  34
  35 * tests/run_tests.sh UNIT/tool
  36
  37   runs all of the "tool" UNIT tests
  38
  39 * tests/run_tests.sh tests/UNIT/eventscripts/00.ctdb.setup.001.sh
  40   tests/run_tests.sh tests/INTEGRATION/simple/basics.001.listnodes.sh
  41
  42   each runs a single specified test case
  43
  44 * tests/run_tests.sh UNIT/eventscripts UNIT/tool tests/UNIT/onnode/0001.sh
  45
  46   runs a combination of UNIT test suites and a single UNIT test
  47
  48 Testing on a cluster
  49 --------------------
  50
  51 INTEGRATION and CLUSTER tests can be run on a real or virtual cluster
  52 using tests/run_cluster_tests.sh (or "tests/run_tests.sh -c").  The
  53 test code needs to be available on all cluster nodes, as well as the
  54 test client node.  The test client node needs to have a nodes file
  55 where the onnode(1) command will find it.
  56
  57 If the all of the cluster nodes have the CTDB git tree in the same
  58 location as on the test client then no special action is necessary.
  59 The simplest way of doing this is to share the tree to cluster nodes
  60 and test clients via NFS.
  61
  62 Alternatively, the tests can be installed on all nodes.  One technique
  63 is to build a package containing the tests and install it on all
  64 nodes.  CTDB developers do a lot of testing this way using the
  65 provided sample packaging, which produces a ctdb-tests RPM package.
  66
  67 Finally, if the test code is installed in a different place on the
  68 cluster nodes, then CTDB_TEST_REMOTE_DIR can be set on the test client
  69 node to point to a directory that contains the test_wrap script on the
  70 cluster nodes.
  71
  72 Running tests under valgrind
  73 ----------------------------
  74
  75 The easiest way of doing this is something like:
  76
  77   VALGRIND="valgrind -q" tests/run_tests ...
  78
  79 This can be used to cause all invocations of the ctdb tool, test
  80 programs and, with local daemons, the ctdbd daemons themselves to run
  81 under valgrind.
  82
  83 How is the ctdb tool invoked?
  84 -----------------------------
  85
  86 $CTDB determines how to invoke the ctdb client.  If not already set
  87 and if $VALGRIND is set, this is set to "$VALGRIND ctdb".  If this is
  88 not already set but $VALGRIND is not set, this is simply set to "ctdb"
  89
  90 Test and debugging variable options
  91 -----------------------------------
  92
  93        CTDB_TEST_MODE
  94
  95            Set this environment variable to enable test mode.
  96
  97            This enables daemons and tools to locate their socket and
  98            PID file relative to CTDB_BASE.
  99
 100            When testing with multiple local daemons on a single
 101            machine this does 3 extra things:
 102
 103            * Disables checks related to public IP addresses
 104
 105            * Speeds up the initial recovery during startup at the
 106              expense of some consistency checking
 107
 108            * Disables real-time scheduling
 109
 110        CTDB_DEBUG_HUNG_SCRIPT_LOGFILE=FILENAME
 111            FILENAME specifies where log messages should go when
 112            debugging hung eventscripts. This is a testing option. See
 113            also CTDB_DEBUG_HUNG_SCRIPT.
 114
 115            No default. Messages go to stdout/stderr and are logged to
 116            the same place as other CTDB log messages.
 117
 118        CTDB_SYS_ETCDIR=DIRECTORY
 119            DIRECTORY containing system configuration files. This is
 120            used to provide alternate configuration when testing and
 121            should not need to be changed from the default.
 122
 123            Default is /etc.
 124
 125        CTDB_RUN_TIMEOUT_MONITOR=yes|no
 126            Whether CTDB should simulate timing out monitor
 127            events in local daemon tests.
 128
 129            Default is no.
 130
 131        CTDB_TEST_SAMBA_VERSION=VERSION
 132
 133             VERSION is a 32-bit number containg the Samba major
 134             version in the most significant 16 bits and the minor
 135             version in the least significant 16 bits.  This can be
 136             used to test CTDB's checking of incompatible versions
 137             without installing an incompatible version.  This is
 138             probably best set like this:
 139
 140                 export CTDB_TEST_SAMBA_VERSION=$(( (4 << 16) | 12 ))
 141
 142        CTDB_VARDIR=DIRECTORY
 143            DIRECTORY containing CTDB files that are modified at runtime.
 144
 145            Defaults to /usr/local/var/lib/ctdb.