external/bsd/atf/dist/doc/atf-test-case.4

   1 .\"
   2 .\" Automated Testing Framework (atf)
   3 .\"
   4 .\" Copyright (c) 2007, 2008 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 15, 2008
  30 .Dt ATF-TEST-CASE 8
  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 routine
  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 A test case always exits with one of the following results:
  83 .Bl -tag -width skippedXX
  84 .It passed
  85 The test case was executed successfully.
  86 .It skipped
  87 The test case could not be executed because some preconditions were not
  88 met.
  89 This is not a failure because it can typically be resolved by adjusting
  90 the system to meet the necessary conditions.
  91 This is always accompanied by a
  92 .Em reason ,
  93 a message describing why the test was skipped.
  94 .It failed
  95 An error appeared during the execution of the test case.
  96 This is always accompanied by a
  97 .Em reason ,
  98 a message describing why the test failed.
  99 .El
 100 .Ss Input/output
 101 Test cases are free to print whatever they want to their
 102 .Xr stdout 4
 103 and
 104 .Xr stderr 4
 105 file descriptors.
 106 They are, in fact, encouraged to print status information as they execute
 107 to keep the user informed of their actions.
 108 This is specially important for long test cases.
 109 .Pp
 110 Test cases will log their results to an auxiliary file, which is then
 111 collected by the test program they are contained in.
 112 The developer need not care about this as long as he uses the correct
 113 APIs to implement the test cases.
 114 .Ss Meta-data
 115 The following list describes all meta-data properties interpreted
 116 internally by ATF.
 117 You are free to define new properties in your test cases and use them as
 118 you wish.
 119 .Bl -tag -width requireXmachineXX
 120 .It descr
 121 Type: textual.
 122 Required.
 123 .Pp
 124 A brief textual description of the test case's purpose.
 125 Will be shown to the user in reports.
 126 Also good for documentation purposes.
 127 .It ident
 128 Type: textual.
 129 Required.
 130 .Pp
 131 The test case's identifier.
 132 Must be unique inside the test program and should be short but descriptive.
 133 .It require.arch
 134 Type textual.
 135 Optional.
 136 .Pp
 137 A whitespace separated list of architectures that the test case can be run
 138 under without causing errors due to an architecture mismatch.
 139 .It require.config
 140 Type: textual.
 141 Optional.
 142 .Pp
 143 A whitespace separated list of configuration variables that must be defined
 144 to execute the test case.
 145 If any of the required variables is not defined, the test case is
 146 .Em skipped .
 147 .It require.machine
 148 Type textual.
 149 Optional.
 150 .Pp
 151 A whitespace separated list of machine types that the test case can be run
 152 under without causing errors due to a machine type mismatch.
 153 .It require.progs
 154 Type: textual.
 155 Optional.
 156 .Pp
 157 A whitespace separated list of programs that must be present to execute
 158 the test case.
 159 These can be given as plain names, in which case they are looked in the
 160 user's
 161 .Ev PATH ,
 162 or as absolute paths.
 163 If any of the required programs is not found, the test case is
 164 .Em skipped .
 165 .It require.user
 166 Type: textual.
 167 Optional.
 168 .Pp
 169 The required privileges to execute the test case.
 170 Can be one of
 171 .Sq root
 172 or
 173 .Sq unprivileged .
 174 If the requested privileges do not match the current user, the test case is
 175 .Em skipped .
 176 .Pp
 177 .Em NOTE :
 178 In the future, it is expected that the test case will attempt to gain the
 179 necessary privileges on its own before failing.
 180 At the very least, lowering the privileges from the super-user to an
 181 unprivileged user will be supported.
 182 .It timeout
 183 Type: integral.
 184 Required; defaults to
 185 .Sq 300 .
 186 .Pp
 187 Specifies the maximum amount of time the test case can run.
 188 This is particularly useful because some tests can stall either because they
 189 are incorrectly coded or because they trigger an anomalous behavior of the
 190 program.
 191 It is not acceptable for these tests to stall the whole execution of the
 192 test program.
 193 .Pp
 194 Can optionally be set to zero, in which case the test case has no run-time
 195 limit.
 196 This is discouraged.
 197 .El
 198 .Ss Environment
 199 Every time a test case is executed, several environment variables are
 200 cleared or reseted to sane values to ensure they do not make the test fail
 201 due to unexpected conditions.
 202 These variables are:
 203 .Bl -tag -width LCXMESSAGESXX
 204 .It Ev HOME
 205 Set to the work directory's path.
 206 .It Ev LANG
 207 Undefined.
 208 .It Ev LC_ALL
 209 Undefined.
 210 .It Ev LC_COLLATE
 211 Undefined.
 212 .It Ev LC_CTYPE
 213 Undefined.
 214 .It Ev LC_MESSAGES
 215 Undefined.
 216 .It Ev LC_MONETARY
 217 Undefined.
 218 .It Ev LC_NUMERIC
 219 Undefined.
 220 .It Ev LC_TIME
 221 Undefined.
 222 .It Ev TZ
 223 Undefined.
 224 .El
 225 .Ss Work directories
 226 The test program always creates a temporary directory
 227 and switches to it before running the test case's body.
 228 This way the test case is free to modify its current directory as it
 229 wishes, and the test program will be able to clean it up later on in a
 230 safe way, removing any traces of its execution from the system.
 231 .Ss File creation mode mask (umask)
 232 Test cases are always executed with a file creation mode mask (umask) of
 233 .Sq 0022 .
 234 The test case's code is free to change this during execution.
 235 .Sh SEE ALSO
 236 .Xr atf-test-program 1 ,
 237 .Xr atf-formats 5 ,
 238 .Xr atf 7