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, 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.py. 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 For a full description of the subunit protocol, see the README file in the subunit
  41 repository at http://github.com/testing-cabal/subunit.
  42
  43 The following commands are Samba extensions to Subunit:
  44
  45 testsuite-count
  46 ~~~~~~~~~~~~~~~
  47 testsuite-count: number
  48
  49 Announce the number of tests that is going to be run.
  50
  51 start-testsuite
  52 ~~~~~~~~~~~~~~~
  53 start-testsuite: name
  54
  55 The testsuite name is used as prefix for all containing tests.
  56
  57 skip-testsuite
  58 ~~~~~~~~~~~~~~
  59 skip-testsuite: name
  60
  61 Mark the testsuite with the specified name as skipped.
  62
  63 testsuite-success
  64 ~~~~~~~~~~~~~~~~~
  65 testsuite-success: name
  66
  67 Indicate that the testsuite has succeeded successfully.
  68
  69 testsuite-fail
  70 ~~~~~~~~~~~~~~
  71 testsuite-fail: name
  72
  73 Indicate that a testsuite has failed.
  74
  75 Environments
  76 ============
  77 Tests often need to run against a server with particular things set up,
  78 a "environment". This environment is provided by the test "target": Samba 3,
  79 Samba 4 or Windows.
  80
  81 The environments are currently available include
  82
  83  - none: No server set up, no variables set.
  84  - dc,s3dc: Domain controller set up. The following environment variables will
  85    be set:
  86
  87      * USERNAME: Administrator user name
  88      * PASSWORD: Administrator password
  89      * DOMAIN: Domain name
  90      * REALM: Realm name
  91      * SERVER: DC host name
  92      * SERVER_IP: DC IPv4 address
  93      * SERVER_IPV6: DC IPv6 address
  94      * NETBIOSNAME: DC NetBIOS name
  95      * NETIOSALIAS: DC NetBIOS alias
  96
  97  - member,s4member,s3member: Domain controller and member server that is joined to it set up. The
  98    following environment variables will be set:
  99
 100      * USERNAME: Domain administrator user name
 101      * PASSWORD: Domain administrator password
 102      * DOMAIN: Domain name
 103      * REALM: Realm name
 104      * SERVER: Name of the member server
 105
 106 See Samba.pm, Samba3.pm and Samba4.pm for the full list.
 107
 108 Running tests
 109 =============
 110
 111 To run all the tests use::
 112
 113    make test
 114
 115 To run a quicker subset run::
 116
 117    make quicktest
 118
 119 To run a specific test, use this syntax::
 120
 121    make test TESTS=testname
 122
 123 for example::
 124
 125    make test TESTS=samba4.BASE-DELETE
 126