s4:local_password LDB module - change counter variables to "unsigned" where appropriate
[ira/wip.git] / 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 selftest/samba{3,4}_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