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