/tests/README

 1Pdsh Tests
 2----------
 3
 4This directory contains many basic test scripts for pdsh
 5and its modules. The test framework is borrowed from the
 6core Git testsuite, and thus shares many of the Git
 7test features, including output in the Test Anything
 8Protocol (TAP, testanything.org) format.
 9
10Running Tests
11-------------
12
13Tests may be run in 3 different ways, the easiest of which
14is by issuing "make check" from this directory or the top
15level pdsh build directory. The tests may also all be
16invoked via ./runtests.sh. Finally, since the tests output
17TAP, the tests may be run with any TAP harness, most
18notably the prove(1) command, e.g.
19
20 prove --timer -j 4 t[0-9]*.sh
21 [15:47:54] t0002-internal.sh ........ ok       79 ms
22 [15:47:54] t0101-dshgroup.sh ........ ok      263 ms
23 [15:47:54] t1000-dshbak.sh .......... ok      365 ms
24 [15:47:54] t0004-module-loading.sh .. ok      329 ms
25 [15:47:54] t0003-wcoll.sh ........... ok      569 ms
26 [15:47:54] t0001-basic.sh ........... ok      676 ms
27 [15:47:54]
28 All tests successful.
29 Files=8, Tests=55,  1 wallclock secs ( 0.13 usr  0.05 sys +  0.75 cusr  1.64 csys =  2.57 CPU)
30 Result: PASS
31
32
33Test scripts may be run individually as well, e.g.
34
35  ./t0003-wcoll.sh
36  ok 1 - hostname range expansion works
37  ok 2 - host range expansion does not strip leading zeros
38  ok 3 - host range expansion handles mixed size suffixes
39  ...
40  ok 11 - WCOLL environment variable works
41  ok 12 - ranges can be embedded in wcoll files
42  # passed all 12 test(s)
43  1..12
44
45Tests also support a standard set of options:
46
47 -v, --verbose       Print commands being run and their output
48 -d, --debug         Enable any test debugging
49 -i, --immediate     Fail immediately on first failed test
50 -l, --long-tests    Run additional long-running tests
51     --tee           Also write test output to test-results/$TEST_NAME.out
52	 --root=dir      Create 'trash' directories under "dir"
53
54Skipping Tests
55--------------
56
57The environment variable PDSH_SKIP_TESTS is a space separated list
58of patterns that tells which tests to skip, and can either match
59the test number t[0-9]{4} to skip an entire test script, or
60have an appended .$number to skip a particular test in a test script.
61
62Test Naming
63-------------
64
65The test files are by convention named
66
67    tNNNN-<name>.sh
68
69where N is a decimal digit. For pdsh, only the first digit has meaning,
70where so far the only digits used are:
71
72   0 - basic pdsh functionality tests
73   1 - pdsh misc module tests
74   2 - pdsh rcmd module tests
75   5 - other tools tests (e.g. dshbak)
76   6 - pdsh regression tests (that don't fit in other categories)
77
78Obviously, tests are run in numerical order, so if one test depends on
79another it should be numbered higher.
80