1ATF-TEST-CASE(4)         BSD Kernel Interfaces Manual         ATF-TEST-CASE(4)
2

NAME

4     atf-test-case — generic description of test cases
5

DESCRIPTION

7     A test case is a piece of code that stress-tests a specific feature of
8     the software.  This feature is typically self-contained enough, either in
9     the amount of code that implements it or in the general idea that
10     describes it, to warrant its independent testing.  Given this, test cases
11     are very fine-grained, but they attempt to group similar smaller tests
12     which are semantically related.
13
14     A test case is defined by three components regardless of the language it
15     is implemented in: a header, a body and a cleanup routine.  The header
16     is, basically, a declarative piece of code that defines several proper‐
17     ties to describe what the test case does and how it behaves.  In other
18     words: it defines the test case's meta-data, further described in the
19     Meta-data section.  The body is the test case itself.  It executes all
20     actions needed to reproduce the test, and checks for failures.  This body
21     is only executed if the abstract conditions specified by the header are
22     met.  The cleanup routine is a piece of code always executed after the
23     body, regardless of the exit status of the test case.  It can be used to
24     undo side-effects of the test case.  Note that almost all side-effects of
25     a test case are automatically cleaned up by the library; this is
26     explained in more detail in the rest of this document.
27
28     It is extremely important to keep the separation between a test case's
29     header and body well-defined, because the header is always parsed,
30     whereas the body is only executed when the conditions defined in the
31     header are met and when the user specifies that test case.
32
33     At last, test cases are always contained into test programs.  The test
34     programs act as a front-end to them, providing a consistent interface to
35     the user and several APIs to ease their implementation.
36
37   Results
38     Upon termination, a test case reports a status and, optionally, a textual
39     reason describing why the test reported such status.  The caller must
40     ensure that the test case really performed the task that its status
41     describes, as the test program may be bogus and therefore providing a
42     misleading result (e.g. providing a result that indicates success but the
43     error code of the program says otherwise).
44
45     The possible exit status of a test case are one of the following:
46
47     expected_death      The test case expects to terminate abruptly.
48
49     expected_exit       The test case expects to exit cleanly.
50
51     expected_failure    The test case expects to exit with a controller
52                         fatal/non-fatal failure.  If this happens, the test
53                         program exits with a success error code.
54
55     expected_signal     The test case expects to receive a signal that makes
56                         it terminate.
57
58     expected_timeout    The test case expects to execute for longer than its
59                         timeout.
60
61     passed              The test case was executed successfully.  The test
62                         program exits with a success error code.
63
64     skipped             The test case could not be executed because some pre‐
65                         conditions were not met.  This is not a failure
66                         because it can typically be resolved by adjusting the
67                         system to meet the necessary conditions.  This is
68                         always accompanied by a reason, a message describing
69                         why the test was skipped.  The test program exits
70                         with a success error code.
71
72     failed              An error appeared during the execution of the test
73                         case.  This is always accompanied by a reason, a mes‐
74                         sage describing why the test failed.  The test pro‐
75                         gram exits with a failure error code.
76
77     The usefulness of the ‘expected_*’ results comes when writing test cases
78     that verify known failures caused, in general, due to programming errors
79     (aka bugs).  Whenever the faulty condition that the ‘expected_*’ result
80     is trying to cover is fixed, then the test case will be reported as
81     ‘failed’ and the developer will have to adjust it to match its new condi‐
82     tion.
83
84     It is important to note that all ‘expected_*’ results are only provided
85     as a hint to the caller; the caller must verify that the test case did
86     actually terminate as the expected condition says.
87
88   Input/output
89     Test cases are free to print whatever they want to their stdout(4) and
90     stderr(4) file descriptors.  They are, in fact, encouraged to print sta‐
91     tus information as they execute to keep the user informed of their
92     actions.  This is specially important for long test cases.
93
94     Test cases will log their results to an auxiliary file, which is then
95     collected by the test program they are contained in.  The developer need
96     not care about this as long as he uses the correct APIs to implement the
97     test cases.
98
99     The standard input of the test cases is unconditionally connected to
100     ‘/dev/zero’.
101
102   Meta-data
103     The following list describes all meta-data properties interpreted inter‐
104     nally by ATF.  You are free to define new properties in your test cases
105     and use them as you wish, but non-standard properties must be prefixed by
106     ‘X-’.
107
108     descr              Type: textual.  Required.
109
110                        A brief textual description of the test case's pur‐
111                        pose.  Will be shown to the user in reports.  Also
112                        good for documentation purposes.
113
114     has.cleanup        Type: boolean.  Optional.
115
116                        If set to true, specifies that the test case has a
117                        cleanup routine that has to be executed by atf-run(1)
118                        during the cleanup phase of the execution.  This prop‐
119                        erty is automatically set by the framework when defin‐
120                        ing a test case with a cleanup routine, so it should
121                        never be set by hand.
122
123     ident              Type: textual.  Required.
124
125                        The test case's identifier.  Must be unique inside the
126                        test program and should be short but descriptive.
127
128     require.arch       Type: textual.  Optional.
129
130                        A whitespace separated list of architectures that the
131                        test case can be run under without causing errors due
132                        to an architecture mismatch.
133
134     require.config     Type: textual.  Optional.
135
136                        A whitespace separated list of configuration variables
137                        that must be defined to execute the test case.  If any
138                        of the required variables is not defined, the test
139                        case is skipped.
140
141     require.files      Type: textual.  Optional.
142
143                        A whitespace separated list of files that must be
144                        present to execute the test case.  The names of these
145                        files must be absolute paths.  If any of the required
146                        files is not found, the test case is skipped.
147
148     require.machine    Type: textual.  Optional.
149
150                        A whitespace separated list of machine types that the
151                        test case can be run under without causing errors due
152                        to a machine type mismatch.
153
154     require.memory     Type: integer.  Optional.  Specifies the minimum
155                        amount of physical memory needed by the test.  The
156                        value can have a size suffix such as ‘K’, ‘M’, ‘G’ or
157                        ‘T’ to make the amount of bytes easier to type and
158                        read.
159
160     require.progs      Type: textual.  Optional.
161
162                        A whitespace separated list of programs that must be
163                        present to execute the test case.  These can be given
164                        as plain names, in which case they are looked in the
165                        user's PATH, or as absolute paths.  If any of the
166                        required programs is not found, the test case is
167                        skipped.
168
169     require.user       Type: textual.  Optional.
170
171                        The required privileges to execute the test case.  Can
172                        be one of ‘root’ or ‘unprivileged’.
173
174                        If the test case is running as a regular user and this
175                        property is ‘root’, the test case is skipped.
176
177                        If the test case is running as root and this property
178                        is ‘unprivileged’, atf-run(1) will automatically drop
179                        the privileges if the ‘unprivileged-user’ configura‐
180                        tion property is set; otherwise the test case is
181                        skipped.
182
183     timeout            Type: integral.  Optional; defaults to ‘300’.
184
185                        Specifies the maximum amount of time the test case can
186                        run.  This is particularly useful because some tests
187                        can stall either because they are incorrectly coded or
188                        because they trigger an anomalous behavior of the pro‐
189                        gram.  It is not acceptable for these tests to stall
190                        the whole execution of the test program.
191
192                        Can optionally be set to zero, in which case the test
193                        case has no run-time limit.  This is discouraged.
194
195   Environment
196     Every time a test case is executed, several environment variables are
197     cleared or reseted to sane values to ensure they do not make the test
198     fail due to unexpected conditions.  These variables are:
199
200     HOME           Set to the work directory's path.
201
202     LANG           Undefined.
203
204     LC_ALL         Undefined.
205
206     LC_COLLATE     Undefined.
207
208     LC_CTYPE       Undefined.
209
210     LC_MESSAGES    Undefined.
211
212     LC_MONETARY    Undefined.
213
214     LC_NUMERIC     Undefined.
215
216     LC_TIME        Undefined.
217
218     TZ             Hardcoded to ‘UTC’.
219
220   Work directories
221     The test program always creates a temporary directory and switches to it
222     before running the test case's body.  This way the test case is free to
223     modify its current directory as it wishes, and the runtime engine will be
224     able to clean it up later on in a safe way, removing any traces of its
225     execution from the system.  To do so, the runtime engine will perform a
226     recursive removal of the work directory without crossing mount points; if
227     a mount point is found, the file system will be unmounted (if possible).
228
229   File creation mode mask (umask)
230     Test cases are always executed with a file creation mode mask (umask) of
231     ‘0022’.  The test case's code is free to change this during execution.
232

SEE ALSO

234     atf-run(1), atf-test-program(1), atf-formats(5), atf(7)
235
236BSD                            January 13, 2011                            BSD
Impressum