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