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