selftest/README

   1 # vim: ft=rst
   2
   3 This directory contains test scripts that are useful for running a
   4 bunch of tests all at once.
   5
   6 There are two parts to this:
   7
   8  * The test runner (selftest/selftest.pl)
   9  * The test formatter
  10
  11 selftest.pl simply outputs subunit, which can then be formatted or analyzed
  12 by tools that understand the subunit protocol. One of these tools is
  13 format-subunit.pl, which is used by default as part of "make test".
  14
  15 Available testsuites
  16 ====================
  17 The available testsuites are obtained from a script, usually
  18 source{3,4}/selftest/tests.sh. This script should for each testsuite output
  19 the name of the test, the command to run and the environment that should be
  20 provided. Use the included "plantest" function to generate the required output.
  21
  22 Testsuite behaviour
  23 ===================
  24
  25 Exit code
  26 ------------
  27 The testsuites should exit with a non-zero exit code if at least one
  28 test failed. Skipped tests should not influence the exit code.
  29
  30 Output format
  31 -------------
  32 Testsuites can simply use the exit code to indicate whether all of their
  33 tests have succeeded or one or more have failed. It is also possible to
  34 provide more granular information using the Subunit protocol.
  35
  36 This protocol works by writing simple messages to standard output. Any
  37 messages that can not be interpreted by this protocol are considered comments
  38 for the last announced test.
  39
  40 Accepted commands are:
  41
  42 test
  43 ~~~~
  44 test: <NAME>
  45
  46 Announce that a new test with the specified name is starting
  47
  48 success
  49 ~~~~~~~
  50 success: <NAME>
  51
  52 Announce that the test with the specified name is done and ran successfully.
  53
  54 failure
  55 ~~~~~~~
  56 failure: <NAME>
  57 failure: <NAME> [ REASON ]
  58
  59 Announce that the test with the specified name failed. Optionally, it is
  60 possible to specify a reason it failed.
  61
  62 The alias "fail" will also work.
  63
  64 xfail
  65 ~~~~~
  66 xfail: <NAME>
  67 xfail: <NAME> [ REASON ]
  68
  69 Announce that the test with the specified name failed but that the failure
  70 was expected, e.g. it's a test for a known bug that hasn't been fixed yet.
  71 Alternatively it is also possible to simply return "failure:" here but
  72 specify in the samba4-knownfailures file that it is failing.
  73
  74 skip
  75 ~~~~
  76 skip: <NAME>
  77 skip: <NAME> [ REASON ]
  78
  79 Announce that the test with the specified name was skipped. Optionally a
  80 reason can be specified.
  81
  82 time
  83 ~~~~
  84 time: YYYY-MM-DD HH:mm:ssZ
  85
  86 Announce the current time. This may be used to calculate the duration of
  87 various tests.
  88
  89 The following are Samba extensions to Subunit:
  90
  91 testsuite-count
  92 ~~~~~~~~~~~~~~~
  93 testsuite-count: number
  94
  95 Announce the number of tests that is going to be run.
  96
  97 start-testsuite
  98 ~~~~~~~~~
  99 start-testsuite: name
 100
 101 The testsuite name is used as prefix for all containing tests.
 102
 103 skip-testsuite
 104 ~~~~~~~~~~~~~~
 105 skip-testsuite: name
 106
 107 Mark the testsuite with the specified name as skipped.
 108
 109 testsuite-success
 110 ~~~~~~~~~~~~~~~~~
 111 testsuite-success: name
 112
 113 Indicate that the testsuite has succeeded successfully.
 114
 115 testsuite-fail
 116 ~~~~~~~~~~~~~~
 117 testsuite-fail: name
 118
 119 Indicate that a testsuite has failed.
 120
 121 Environments
 122 ============
 123 Tests often need to run against a server with particular things set up,
 124 a "environment". This environment is provided by the test "target": Samba 3,
 125 Samba 4 or Windows.
 126
 127 The following environments are currently available:
 128
 129  - none: No server set up, no variables set.
 130  - dc: Domain controller set up. The following environment variables will
 131    be set:
 132
 133      * USERNAME: Administrator user name
 134          * PASSWORD: Administrator password
 135          * DOMAIN: Domain name
 136          * REALM: Realm name
 137          * SERVER: DC host name
 138          * SERVER_IP: DC IPv4 address
 139          * NETBIOSNAME: DC NetBIOS name
 140          * NETIOSALIAS: DC NetBIOS alias
 141
 142  - member: Domain controller and member server that is joined to it set up. The
 143    following environment variables will be set:
 144
 145      * USERNAME: Domain administrator user name
 146          * PASSWORD: Domain administrator password
 147          * DOMAIN: Domain name
 148          * REALM: Realm name
 149          * SERVER: Name of the member server
 150
 151
 152 Running tests
 153 =============
 154
 155 To run all the tests use::
 156
 157    make test
 158
 159 To run a quick subset (aiming for about 1 minute of testing) run::
 160
 161    make quicktest
 162
 163 To run a specific test, use this syntax::
 164
 165    make test TESTS=testname
 166
 167 for example::
 168
 169    make test TESTS=samba4.BASE-DELETE
 170