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