| blob | 9921a3ae95b623423010ac5359f6473bf96696e5 |
1 .\" $NetBSD: atf-test-case.4,v 1.3 2014/12/10 04:38:04 christos Exp $
2 .\"
3 .\"
4 .\" Automated Testing Framework (atf)
5 .\"
6 .\" Copyright (c) 2007 The NetBSD Foundation, Inc.
7 .\" All rights reserved.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND
19 .\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
20 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
21 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22 .\" IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY
23 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
25 .\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
27 .\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
28 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
29 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 .\"
31 .Dd January 13, 2011
32 .Dt ATF-TEST-CASE 4
33 .Os
34 .Sh NAME
35 .Nm atf-test-case
36 .Nd generic description of test cases
37 .Sh DESCRIPTION
38 A
39 .Em test case
40 is a piece of code that stress-tests a specific feature of the software.
41 This feature is typically self-contained enough, either in the amount of
42 code that implements it or in the general idea that describes it, to
43 warrant its independent testing.
44 Given this, test cases are very fine-grained, but they attempt to group
45 similar smaller tests which are semantically related.
46 .Pp
47 A test case is defined by three components regardless of the language it is
48 implemented in: a header, a body and a cleanup routine.
49 The
50 .Em header
51 is, basically, a declarative piece of code that defines several
52 properties to describe what the test case does and how it behaves.
53 In other words: it defines the test case's
54 .Em meta-data ,
55 further described in the
56 .Sx Meta-data
57 section.
58 The
59 .Em body
60 is the test case itself.
61 It executes all actions needed to reproduce the test, and checks for
62 failures.
63 This body is only executed if the abstract conditions specified by the
64 header are met.
65 The
66 .Em cleanup
67 routine is a piece of code always executed after the body, regardless of
68 the exit status of the test case.
69 It can be used to undo side-effects of the test case.
70 Note that almost all side-effects of a test case are automatically cleaned
71 up by the library; this is explained in more detail in the rest of this
72 document.
73 .Pp
74 It is extremely important to keep the separation between a test case's
75 header and body well-defined, because the header is
76 .Em always
77 parsed, whereas the body is only executed when the conditions defined in
78 the header are met and when the user specifies that test case.
79 .Pp
80 At last, test cases are always contained into test programs.
81 The test programs act as a front-end to them, providing a consistent
82 interface to the user and several APIs to ease their implementation.
83 .Ss Results
84 Upon termination, a test case reports a status and, optionally, a textual
85 reason describing why the test reported such status.
86 The caller must ensure that the test case really performed the task that its
87 status describes, as the test program may be bogus and therefore providing a
88 misleading result (e.g. providing a result that indicates success but the
89 error code of the program says otherwise).
90 .Pp
91 The possible exit status of a test case are one of the following:
92 .Bl -tag -width expectedXfailureXX
93 .It expected_death
94 The test case expects to terminate abruptly.
95 .It expected_exit
96 The test case expects to exit cleanly.
97 .It expected_failure
98 The test case expects to exit with a controller fatal/non-fatal failure.
99 If this happens, the test program exits with a success error code.
100 .It expected_signal
101 The test case expects to receive a signal that makes it terminate.
102 .It expected_timeout
103 The test case expects to execute for longer than its timeout.
104 .It passed
105 The test case was executed successfully.
106 The test program exits with a success error code.
107 .It skipped
108 The test case could not be executed because some preconditions were not
109 met.
110 This is not a failure because it can typically be resolved by adjusting
111 the system to meet the necessary conditions.
112 This is always accompanied by a
113 .Em reason ,
114 a message describing why the test was skipped.
115 The test program exits with a success error code.
116 .It failed
117 An error appeared during the execution of the test case.
118 This is always accompanied by a
119 .Em reason ,
120 a message describing why the test failed.
121 The test program exits with a failure error code.
122 .El
123 .Pp
124 The usefulness of the
125 .Sq expected_*
126 results comes when writing test cases that verify known failures caused,
127 in general, due to programming errors (aka bugs).
128 Whenever the faulty condition that the expectation is trying to convery is
129 fixed, then the test case will be reported as
130 .Sq failed
131 and the developer will have to adjust it to match its new condition.
132 .Pp
133 It is important to note that all
134 .Sq expected_*
135 results are only provided as a
136 .Em hint
137 to the caller; the caller must verify that the test case did actually terminate
138 as the expected condition says.
139 .Ss Input/output
140 Test cases are free to print whatever they want to their
141 .Xr stdout 4
142 and
143 .Xr stderr 4
144 file descriptors.
145 They are, in fact, encouraged to print status information as they execute
146 to keep the user informed of their actions.
147 This is specially important for long test cases.
148 .Pp
149 Test cases will log their results to an auxiliary file, which is then
150 collected by the test program they are contained in.
151 The developer need not care about this as long as he uses the correct
152 APIs to implement the test cases.
153 .Pp
154 The standard input of the test cases is unconditionally connected to
155 .Sq /dev/zero .
156 .Ss Meta-data
157 The following list describes all meta-data properties interpreted
158 internally by ATF.
159 You are free to define new properties in your test cases and use them as
160 you wish, but non-standard properties must be prefixed by
161 .Sq X- .
162 .Bl -tag -width requireXmachineXX
163 .It descr
164 Type: textual.
165 Required.
166 .Pp
167 A brief textual description of the test case's purpose.
168 Will be shown to the user in reports.
169 Also good for documentation purposes.
170 .It has.cleanup
171 Type: boolean.
172 Optional.
173 .Pp
174 If set to true, specifies that the test case has a cleanup routine that has
175 to be executed by
176 .Xr atf-run 1
177 during the cleanup phase of the execution.
178 This property is automatically set by the framework when defining a test case
179 with a cleanup routine, so it should never be set by hand.
180 .It ident
181 Type: textual.
182 Required.
183 .Pp
184 The test case's identifier.
185 Must be unique inside the test program and should be short but descriptive.
186 .It require.arch
187 Type: textual.
188 Optional.
189 .Pp
190 A whitespace separated list of architectures that the test case can be run
191 under without causing errors due to an architecture mismatch.
192 .It require.config
193 Type: textual.
194 Optional.
195 .Pp
196 A whitespace separated list of configuration variables that must be defined
197 to execute the test case.
198 If any of the required variables is not defined, the test case is
199 .Em skipped .
200 .It require.files
201 Type: textual.
202 Optional.
203 .Pp
204 A whitespace separated list of files that must be present to execute the
205 test case.
206 The names of these files must be absolute paths.
207 If any of the required files is not found, the test case is
208 .Em skipped .
209 .It require.machine
210 Type: textual.
211 Optional.
212 .Pp
213 A whitespace separated list of machine types that the test case can be run
214 under without causing errors due to a machine type mismatch.
215 .It require.memory
216 Type: integer.
217 Optional.
218 Specifies the minimum amount of physical memory needed by the test.
219 The value can have a size suffix such as
220 .Sq K ,
221 .Sq M ,
222 .Sq G
223 or
224 .Sq T
225 to make the amount of bytes easier to type and read.
226 .It require.progs
227 Type: textual.
228 Optional.
229 .Pp
230 A whitespace separated list of programs that must be present to execute
231 the test case.
232 These can be given as plain names, in which case they are looked in the
233 user's
234 .Ev PATH ,
235 or as absolute paths.
236 If any of the required programs is not found, the test case is
237 .Em skipped .
238 .It require.user
239 Type: textual.
240 Optional.
241 .Pp
242 The required privileges to execute the test case.
243 Can be one of
244 .Sq root
245 or
246 .Sq unprivileged .
247 .Pp
248 If the test case is running as a regular user and this property is
249 .Sq root ,
250 the test case is
251 .Em skipped .
252 .Pp
253 If the test case is running as root and this property is
254 .Sq unprivileged ,
255 .Xr atf-run 1
256 will automatically drop the privileges if the
257 .Sq unprivileged-user
258 configuration property is set; otherwise the test case is
259 .Em skipped .
260 .It timeout
261 Type: integral.
262 Optional; defaults to
263 .Sq 300 .
264 .Pp
265 Specifies the maximum amount of time the test case can run.
266 This is particularly useful because some tests can stall either because they
267 are incorrectly coded or because they trigger an anomalous behavior of the
268 program.
269 It is not acceptable for these tests to stall the whole execution of the
270 test program.
271 .Pp
272 Can optionally be set to zero, in which case the test case has no run-time
273 limit.
274 This is discouraged.
275 .El
276 .Ss Environment
277 Every time a test case is executed, several environment variables are
278 cleared or reseted to sane values to ensure they do not make the test fail
279 due to unexpected conditions.
280 These variables are:
281 .Bl -tag -width LCXMESSAGESXX
282 .It Ev HOME
283 Set to the work directory's path.
284 .It Ev LANG
285 Undefined.
286 .It Ev LC_ALL
287 Undefined.
288 .It Ev LC_COLLATE
289 Undefined.
290 .It Ev LC_CTYPE
291 Undefined.
292 .It Ev LC_MESSAGES
293 Undefined.
294 .It Ev LC_MONETARY
295 Undefined.
296 .It Ev LC_NUMERIC
297 Undefined.
298 .It Ev LC_TIME
299 Undefined.
300 .It Ev TZ
301 Hardcoded to
302 .Sq UTC .
303 .El
304 .Ss Work directories
305 The test program always creates a temporary directory
306 and switches to it before running the test case's body.
307 This way the test case is free to modify its current directory as it
308 wishes, and the runtime engine will be able to clean it up later on in a
309 safe way, removing any traces of its execution from the system.
310 To do so, the runtime engine will perform a recursive removal of the work
311 directory without crossing mount points; if a mount point is found, the
312 file system will be unmounted (if possible).
313 .Ss File creation mode mask (umask)
314 Test cases are always executed with a file creation mode mask (umask) of
315 .Sq 0022 .
316 The test case's code is free to change this during execution.
317 .Sh SEE ALSO
318 .Xr atf-run 1 ,
319 .Xr atf-test-program 1 ,
320 .Xr atf-formats 5 ,
321 .Xr atf 7