contrib/atf/doc/atf-test-case.4

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