1*11be35a1SLionel Sambuc.\" Copyright 2012 Google Inc. 2*11be35a1SLionel Sambuc.\" All rights reserved. 3*11be35a1SLionel Sambuc.\" 4*11be35a1SLionel Sambuc.\" Redistribution and use in source and binary forms, with or without 5*11be35a1SLionel Sambuc.\" modification, are permitted provided that the following conditions are 6*11be35a1SLionel Sambuc.\" met: 7*11be35a1SLionel Sambuc.\" 8*11be35a1SLionel Sambuc.\" * Redistributions of source code must retain the above copyright 9*11be35a1SLionel Sambuc.\" notice, this list of conditions and the following disclaimer. 10*11be35a1SLionel Sambuc.\" * Redistributions in binary form must reproduce the above copyright 11*11be35a1SLionel Sambuc.\" notice, this list of conditions and the following disclaimer in the 12*11be35a1SLionel Sambuc.\" documentation and/or other materials provided with the distribution. 13*11be35a1SLionel Sambuc.\" * Neither the name of Google Inc. nor the names of its contributors 14*11be35a1SLionel Sambuc.\" may be used to endorse or promote products derived from this software 15*11be35a1SLionel Sambuc.\" without specific prior written permission. 16*11be35a1SLionel Sambuc.\" 17*11be35a1SLionel Sambuc.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18*11be35a1SLionel Sambuc.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19*11be35a1SLionel Sambuc.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 20*11be35a1SLionel Sambuc.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 21*11be35a1SLionel Sambuc.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 22*11be35a1SLionel Sambuc.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 23*11be35a1SLionel Sambuc.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24*11be35a1SLionel Sambuc.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25*11be35a1SLionel Sambuc.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26*11be35a1SLionel Sambuc.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 27*11be35a1SLionel Sambuc.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28*11be35a1SLionel Sambuc.Dd September 9, 2012 29*11be35a1SLionel Sambuc.Dt KYUA-ATF-INTERFACE 1 30*11be35a1SLionel Sambuc.Os 31*11be35a1SLionel Sambuc.Sh NAME 32*11be35a1SLionel Sambuc.Nm atf-interface 33*11be35a1SLionel Sambuc.Nd Description of the ATF test program interface 34*11be35a1SLionel Sambuc.Sh DESCRIPTION 35*11be35a1SLionel SambucThe interface of ATF test programs is the interface of the test 36*11be35a1SLionel Sambucprograms linked to the 37*11be35a1SLionel Sambuc.Nm atf-c , 38*11be35a1SLionel Sambuc.Nm atf-c++ 39*11be35a1SLionel Sambucand 40*11be35a1SLionel Sambuc.Nm atf-sh 41*11be35a1SLionel Sambuclibraries provided by ATF. 42*11be35a1SLionel Sambuc.Pp 43*11be35a1SLionel SambucThe ATF interface can be understood as the mechanisms used by test programs 44*11be35a1SLionel Sambucto communicate with the runtime engine as well as the assumptions that test 45*11be35a1SLionel Sambucprograms and test cases can make while running. 46*11be35a1SLionel Sambuc.Pp 47*11be35a1SLionel SambucA test case is the most basic part of a test suite. A test case is 48*11be35a1SLionel Sambucsupposed to reproduce one, and only one, scenario. For example: if the 49*11be35a1SLionel Sambucitem under test was a function, the test case would provide a single set of 50*11be35a1SLionel Sambucinput parameters to the function and check its output; If the item under 51*11be35a1SLionel Sambuctest was a binary, the test case would provide a single set of arguments to 52*11be35a1SLionel Sambucthe program and check its behavior. 53*11be35a1SLionel Sambuc.Ss Test case parts 54*11be35a1SLionel SambucTest cases have three parts: 55*11be35a1SLionel Sambuc.Bl -tag -width cleanupXX 56*11be35a1SLionel Sambuc.It Head 57*11be35a1SLionel SambucProgrammatically defines metadata properties. The head must not perform 58*11be35a1SLionel Sambucany other thing than defining such properties. In particular, no testing 59*11be35a1SLionel Sambucwhatsoever can happen in the head. (Ideally the definition of metadata 60*11be35a1SLionel Sambucproperties would not happen programmatically.) 61*11be35a1SLionel Sambuc.It Body 62*11be35a1SLionel SambucThe actual test case which performs any desired testing and reports a 63*11be35a1SLionel Sambucresult. The body is executed by the runtime engine in a deterministic way; 64*11be35a1SLionel Sambucsee the isolation section below. 65*11be35a1SLionel Sambuc.It Cleanup 66*11be35a1SLionel SambucAn optional cleanup routine. Note that the runtime engine will attempt to 67*11be35a1SLionel Sambucclean up the work directory automatically, so this routine should only be 68*11be35a1SLionel Sambucprovided in cases where the test modifies system-wide state not known by 69*11be35a1SLionel Sambucthe runtime engine. The cleanup part is executed in the same directory as 70*11be35a1SLionel Sambucthe body. However, the body and the cleanup parts 71*11be35a1SLionel Sambuc.Em do not share the same process space ; 72*11be35a1SLionel Sambucthe only way to pass data around from the body to the cleanup is by means 73*11be35a1SLionel Sambucof files in the work directory. 74*11be35a1SLionel Sambuc.El 75*11be35a1SLionel Sambuc.Ss Metadata properties 76*11be35a1SLionel SambucThe following test case metadata properties must be exported in the test 77*11be35a1SLionel Sambuccase list for every test case: 78*11be35a1SLionel Sambuc.Bl -tag -width XX 79*11be35a1SLionel Sambuc.It Va ident 80*11be35a1SLionel SambucSingle-word string. The name of the test case. Must be unique within the 81*11be35a1SLionel Sambuctest program. 82*11be35a1SLionel Sambuc.El 83*11be35a1SLionel Sambuc.Pp 84*11be35a1SLionel SambucThe following test case metadata properties may be exported in the 85*11be35a1SLionel Sambuctest case list for every test case: 86*11be35a1SLionel Sambuc.Bl -tag -width XX 87*11be35a1SLionel Sambuc.It Va descr 88*11be35a1SLionel SambucMulti-word string. A textual description for the test case. Usually, 89*11be35a1SLionel Sambucproviding a descriptive identifier is better than providing a textual 90*11be35a1SLionel Sambucdescription. 91*11be35a1SLionel Sambuc.It Va has.cleanup 92*11be35a1SLionel SambucBoolean. Whether the test case defines a cleanup routine or not. 93*11be35a1SLionel Sambuc.It Va require.arch 94*11be35a1SLionel SambucWhitespace separated list of the architectures required by the test case. 95*11be35a1SLionel SambucIf defined, the test case is skipped unless the host architecture matches 96*11be35a1SLionel Sambucany of the values defined in this property. 97*11be35a1SLionel Sambuc.It Va require.config 98*11be35a1SLionel SambucWhitespace separated list of configuration variable names. The list of 99*11be35a1SLionel Sambucconfiguration variables that must be defined. The test is skipped if any 100*11be35a1SLionel Sambucof these is missing. 101*11be35a1SLionel Sambuc.It Va require.files 102*11be35a1SLionel SambucWhitespace separated list of absolute paths to installed files. If any of 103*11be35a1SLionel Sambucthese files is not found, the test case is skipped. 104*11be35a1SLionel Sambuc.It Va require.machine 105*11be35a1SLionel SambucWhitespace separated list of the machine types required by the test case. 106*11be35a1SLionel SambucIf defined, the test case is skipped unless the host machine type matches 107*11be35a1SLionel Sambucany of the values defined in this property. 108*11be35a1SLionel Sambuc.It Va require.progs 109*11be35a1SLionel SambucWhitespace separated list of program names (either absolute names or base 110*11be35a1SLionel Sambucnames). If any of these programs is not found, the test case is skipped. 111*11be35a1SLionel Sambuc.It Va require.user 112*11be35a1SLionel SambucEither 113*11be35a1SLionel Sambuc.Sq root 114*11be35a1SLionel Sambucor 115*11be35a1SLionel Sambuc.Sq unprivileged . 116*11be35a1SLionel SambucIf 117*11be35a1SLionel Sambuc.Sq root , 118*11be35a1SLionel Sambucthe test case must be run as the superuser or otherwise it is skipped. If 119*11be35a1SLionel Sambuc.Sq unprivileged , 120*11be35a1SLionel Sambucthe test case must be run as an unprivileged user or else it is skipped. 121*11be35a1SLionel Sambuc.It Va timeout 122*11be35a1SLionel SambucInteger. The amount of seconds the test case can run for before it is 123*11be35a1SLionel Sambuckilled by the runtime engine. 124*11be35a1SLionel Sambuc.El 125*11be35a1SLionel Sambuc.Ss Configuration properties 126*11be35a1SLionel SambucThe following properties may be defined by the runtime engine and are 127*11be35a1SLionel Sambucpropagated to the test cases: 128*11be35a1SLionel Sambuc.Bl -tag -width XX 129*11be35a1SLionel Sambuc.It Va unprivileged-user 130*11be35a1SLionel SambucString, optional. Specifies the name of the user under which tests that 131*11be35a1SLionel Sambucset 132*11be35a1SLionel Sambuc.Sq require.user=unprivileged 133*11be35a1SLionel Sambucare executed. 134*11be35a1SLionel Sambuc.El 135*11be35a1SLionel Sambuc.Ss Results 136*11be35a1SLionel SambucA test case must always report a result by creating the results file 137*11be35a1SLionel Sambucspecified through the 138*11be35a1SLionel Sambuc.Fl r 139*11be35a1SLionel Sambucflag. For convenience when running test cases without the runtime engine, 140*11be35a1SLionel Sambucthis file may point to 141*11be35a1SLionel Sambuc.Pa /dev/stdout 142*11be35a1SLionel Sambucor 143*11be35a1SLionel Sambuc.Pa /dev/stderr 144*11be35a1SLionel Sambucin which case the file must not be created (because the creation will 145*11be35a1SLionel Sambucfail). 146*11be35a1SLionel Sambuc.Pp 147*11be35a1SLionel SambucAside from creating the results file, the process in which the test case 148*11be35a1SLionel Sambucruns must terminate in particular ways for the test result to be considered 149*11be35a1SLionel Sambucvalid. 150*11be35a1SLionel Sambuc.Pp 151*11be35a1SLionel SambucIf the test case fails to create the test result, if the test result is 152*11be35a1SLionel Sambuccreated but contains an invalid syntax, or if the termination status of the 153*11be35a1SLionel Sambucprocess does not match the requirements of the test result, the runtime 154*11be35a1SLionel Sambucengine marks the test case as 155*11be35a1SLionel Sambuc.Sq broken . 156*11be35a1SLionel SambucNote that the 157*11be35a1SLionel Sambuc.Sq broken 158*11be35a1SLionel Sambucstate is decided by the runtime engine; a test case cannot report itself as 159*11be35a1SLionel Sambuc.Sq broken . 160*11be35a1SLionel Sambuc.Pp 161*11be35a1SLionel SambucThe general syntax for the results file is as follows: 162*11be35a1SLionel Sambuc.Bd -literal -offset indent 163*11be35a1SLionel Sambuc<status>[[(int)]: reason] 164*11be35a1SLionel Sambuc.Ed 165*11be35a1SLionel Sambuc.Pp 166*11be35a1SLionel SambucThe following results are allowed: 167*11be35a1SLionel Sambuc.Bl -tag -width XX 168*11be35a1SLionel Sambuc.It expected_death 169*11be35a1SLionel SambucThe process is expected to terminate either due to a clean call to 170*11be35a1SLionel Sambuc.Xr exit 3 171*11be35a1SLionel Sambucor due to the reception of a signal. The contents of the file are 172*11be35a1SLionel Sambuc.Sq expected_death: <reason>\\n . 173*11be35a1SLionel SambucExample: 174*11be35a1SLionel Sambuc.Sq expected_death: Calling libdofoo breaks due to bug xyz . 175*11be35a1SLionel Sambuc.It expected_exit 176*11be35a1SLionel SambucThe process is expected to terminate cleanly. The contents of the file are 177*11be35a1SLionel Sambuc.Sq expected_exit: <reason> 178*11be35a1SLionel Sambucif the exit code is irrelevant or 179*11be35a1SLionel Sambuc.Sq expected_exit(<exitcode>): <reason> 180*11be35a1SLionel Sambucif the process must terminate with a given exit code. Examples: 181*11be35a1SLionel Sambuc.Sq expected_exit: Calling bar exits but it should not 182*11be35a1SLionel Sambucor 183*11be35a1SLionel Sambuc.Sq expected_exit(123): Calling bar exits with an unexpected code . 184*11be35a1SLionel Sambuc.It expected_failure 185*11be35a1SLionel SambucThe process must exit cleanly with an 186*11be35a1SLionel Sambuc.Va EXIT_SUCCESS 187*11be35a1SLionel Sambucexit code. The contents of the file are 188*11be35a1SLionel Sambuc.Sq expected_failure: <reason>\\n 189*11be35a1SLionel SambucExample: 190*11be35a1SLionel Sambuc.Sq expected_failure: 2 + 2 = 3 . 191*11be35a1SLionel Sambuc.It expected_signal 192*11be35a1SLionel SambucThe process is expected to terminate due to the reception of a signal. The 193*11be35a1SLionel Sambuccontents of the file are 194*11be35a1SLionel Sambuc.Sq expected_signal: <reason> 195*11be35a1SLionel Sambucif the signal number is irrelevant or 196*11be35a1SLionel Sambuc.Sq expected_signal(<signalno>): <reason> 197*11be35a1SLionel Sambucif the process must terminate due to a particular signal. Examples: 198*11be35a1SLionel Sambuc.Sq expected_signal: Calling bar crashes 199*11be35a1SLionel Sambucor 200*11be35a1SLionel Sambuc.Sq expected_signal(1): Calling bar kills ourselves due to unhandled SIGHUP . 201*11be35a1SLionel Sambuc.It expected_timeout 202*11be35a1SLionel SambucThe process is expected to hang for longer than its 203*11be35a1SLionel Sambuc.Va timeout 204*11be35a1SLionel Sambucmetadata property. Only the runtime engine can control this situation 205*11be35a1SLionel Sambucbecause the runtime engine is the one implementing the timeout 206*11be35a1SLionel Sambucfunctionality. 207*11be35a1SLionel Sambuc.It failed 208*11be35a1SLionel SambucThe process must exit cleanly with an 209*11be35a1SLionel Sambuc.Va EXIT_FAILURE 210*11be35a1SLionel Sambucexit code. The contents of the file are 211*11be35a1SLionel Sambuc.Sq failed: <reason>\\n . 212*11be35a1SLionel SambucExample: 213*11be35a1SLionel Sambuc.Sq failed: Failed on purpose\\n . 214*11be35a1SLionel Sambuc.It passed 215*11be35a1SLionel SambucThe process must exit cleanly with an 216*11be35a1SLionel Sambuc.Va EXIT_SUCCESS 217*11be35a1SLionel Sambucexit code. The contents of the file are 218*11be35a1SLionel Sambuc.Sq passed\\n . 219*11be35a1SLionel Sambuc.It skipped 220*11be35a1SLionel SambucThe process must exit cleanly with an 221*11be35a1SLionel Sambuc.Va EXIT_SUCCESS 222*11be35a1SLionel Sambucexit code. The contents of the file are 223*11be35a1SLionel Sambuc.Sq skipped: <reason>\\n . 224*11be35a1SLionel SambucExample: 225*11be35a1SLionel Sambuc.Sq skipped: Skipped because the foo is not present\\n . 226*11be35a1SLionel Sambuc.El 227*11be35a1SLionel Sambuc.Ss Isolation 228*11be35a1SLionel SambucThe runtime engine attempts to isolate test cases from other test cases in 229*11be35a1SLionel Sambucthe same test program and from the rest of the system by performing what is 230*11be35a1SLionel Sambuccalled 231*11be35a1SLionel Sambuc.Em test case isolation . 232*11be35a1SLionel Sambuc.Pp 233*11be35a1SLionel SambucWhenever the user runs a test program binary by hand (i.e. not through 234*11be35a1SLionel Sambuc.Xr kyua 1 ) , 235*11be35a1SLionel Sambucthe test program will print a warning message stating that test case 236*11be35a1SLionel Sambucisolation does not work and therefore the program may cause side-effects 237*11be35a1SLionel Sambucand/or report invalid values. 238*11be35a1SLionel Sambuc.Pp 239*11be35a1SLionel SambucThe runtime engine must set the 240*11be35a1SLionel Sambuc.Va __RUNNING_INSIDE_ATF_RUN 241*11be35a1SLionel Sambucenvironment variable to the magic value 242*11be35a1SLionel Sambuc.Sq internal-yes-value 243*11be35a1SLionel Sambucto tell the test programs that they are being run with isolation enabled. 244*11be35a1SLionel Sambuc.Pp 245*11be35a1SLionel SambucThe test case isolation performs the following: 246*11be35a1SLionel Sambuc.Bl -tag -width XX 247*11be35a1SLionel Sambuc.It Process space 248*11be35a1SLionel SambucEach test case body and cleanup routines are executed in independent 249*11be35a1SLionel Sambucprocesses. Corollary: the test case can do whatever it wants to the 250*11be35a1SLionel Sambuccurrent process (such as modifying global variables) without having to undo 251*11be35a1SLionel Sambucsuch changes. 252*11be35a1SLionel Sambuc.It Process group 253*11be35a1SLionel SambucThe test case body and cleanup are executed in their own process groups. 254*11be35a1SLionel SambucShould they spawn any children, such children should maintain the same 255*11be35a1SLionel Sambucprocess group. This is done to allow the runtime engine to kill the whole 256*11be35a1SLionel Sambucprocess subtree once the test case finishes (or if the test case hangs). 257*11be35a1SLionel Sambuc.It Work directory 258*11be35a1SLionel SambucThe test case body and its cleanup (if any) are executed in a temporary 259*11be35a1SLionel Sambucdirectory automatically created by the runtime engine. This temporary 260*11be35a1SLionel Sambucdirectory is shared among the body and cleanup parts of a single test case 261*11be35a1SLionel Sambucbut is completely separate from the temporary directories of other tests. 262*11be35a1SLionel SambucCorollary: the test case body and cleanup routines can write to their 263*11be35a1SLionel Sambuccurrent directory without bothering to clean any files and/or directories 264*11be35a1SLionel Sambucthey create. The runtime engine takes care to recursively delete the 265*11be35a1SLionel Sambuctemporary directories after the execution of a test case. Any file systems 266*11be35a1SLionel Sambucmounted within the temporary directory will be unmounted if possible. 267*11be35a1SLionel Sambuc.It Home directory 268*11be35a1SLionel SambucThe 269*11be35a1SLionel Sambuc.Va HOME 270*11be35a1SLionel Sambucenvironment variable is set to the absolute path of the work directory. 271*11be35a1SLionel Sambuc.It Umask 272*11be35a1SLionel SambucThe value of the umask is set to 0022. 273*11be35a1SLionel Sambuc.It Environment 274*11be35a1SLionel SambucThe 275*11be35a1SLionel Sambuc.Va LANG , 276*11be35a1SLionel Sambuc.Va LC_ALL , 277*11be35a1SLionel Sambuc.Va LC_COLLATE , 278*11be35a1SLionel Sambuc.Va LC_CTYPE , 279*11be35a1SLionel Sambuc.Va LC_MESSAGES , 280*11be35a1SLionel Sambuc.Va LC_MONETARY , 281*11be35a1SLionel Sambuc.Va LC_NUMERIC 282*11be35a1SLionel Sambucand 283*11be35a1SLionel Sambuc.Va LC_TIME 284*11be35a1SLionel Sambucvariables are unset. The 285*11be35a1SLionel Sambuc.Va TZ 286*11be35a1SLionel Sambucvariable is set to 287*11be35a1SLionel Sambuc.Sq UTC . 288*11be35a1SLionel Sambuc.It Process limits 289*11be35a1SLionel SambucThe maximum soft core size limit is raised to its corresponding hard limit. 290*11be35a1SLionel SambucThis is a simple, best-effort attempt at allowing test cases to dump core 291*11be35a1SLionel Sambucfor further diagnostic purposes. 292*11be35a1SLionel Sambuc.El 293*11be35a1SLionel Sambuc.Ss Test programs 294*11be35a1SLionel SambucA test program is, simply put, a collection of related test cases. The 295*11be35a1SLionel Sambuctest program can be seen as a command-line dispatcher for the test cases. 296*11be35a1SLionel SambucA test program must provide one or more test cases. If it does not contain 297*11be35a1SLionel Sambucany test case, the runtime system will report it as invalid. 298*11be35a1SLionel Sambuc.Pp 299*11be35a1SLionel SambucTest programs expose their list of test cases in a machine parseable 300*11be35a1SLionel Sambucformat. The runtime engine obtains the list of test cases to know what 301*11be35a1SLionel Sambuctests to run and to know how to set up the environment of each test prior 302*11be35a1SLionel Sambucexecution. The test program must not do any test when asked to dump its 303*11be35a1SLionel Sambuctest case list. 304*11be35a1SLionel Sambuc.Pp 305*11be35a1SLionel SambucThe generic syntax to obtain the list of test cases included in a test 306*11be35a1SLionel Sambucprogram is: 307*11be35a1SLionel Sambuc.Bd -literal -offset indent 308*11be35a1SLionel Sambuc<test-program> -l 309*11be35a1SLionel Sambuc.Ed 310*11be35a1SLionel Sambuc.Pp 311*11be35a1SLionel SambucThe list of test cases follows the following format: 312*11be35a1SLionel Sambuc.Bd -literal -offset indent 313*11be35a1SLionel SambucLIST ::= HEADER NEWLINE TEST_CASES 314*11be35a1SLionel Sambuc 315*11be35a1SLionel SambucHEADER ::= 'Content-Type: application/X-atf-tp; version="1"' 316*11be35a1SLionel SambucNEWLINE ::= '\\n' 317*11be35a1SLionel SambucTEST_CASES ::= TEST_CASE | TEST_CASE NEWLINE TEST_CASES 318*11be35a1SLionel Sambuc 319*11be35a1SLionel SambucTEST_CASE ::= IDENT_PROPERTY PROPERTIES 320*11be35a1SLionel SambucIDENT_PROPERTY ::= 'ident' DELIM STRING NEWLINE 321*11be35a1SLionel SambucDELIM ::= ': ' 322*11be35a1SLionel Sambuc 323*11be35a1SLionel SambucPROPERTIES ::= PROPERTY | PROPERTY PROPERTIES 324*11be35a1SLionel SambucPROPERTY ::= PROPERTY_NAME DELIM STRING NEWLINE 325*11be35a1SLionel SambucPROPERTY_NAME ::= (see below) 326*11be35a1SLionel Sambuc.Ed 327*11be35a1SLionel Sambuc.Pp 328*11be35a1SLionel SambucAn example: 329*11be35a1SLionel Sambuc.Bd -literal -offset indent 330*11be35a1SLionel SambucContent-Type: application/X-atf-tp; version="1" 331*11be35a1SLionel Sambuc 332*11be35a1SLionel Sambucident: addition 333*11be35a1SLionel Sambucdescr: Tests that the addition function works 334*11be35a1SLionel Sambuc 335*11be35a1SLionel Sambucident: subtraction 336*11be35a1SLionel Sambucdescr: Tests that the subtraction function works 337*11be35a1SLionel Sambuc 338*11be35a1SLionel Sambucident: remove 339*11be35a1SLionel Sambucdescr: Tests removing files 340*11be35a1SLionel Sambucrequire.root: true 341*11be35a1SLionel Sambuctimeout: 50 342*11be35a1SLionel Sambuchas.cleanup: true 343*11be35a1SLionel Sambuc.Ed 344*11be35a1SLionel Sambuc.Pp 345*11be35a1SLionel SambucThe syntax to run a test case body part is: 346*11be35a1SLionel Sambuc.Bd -literal -offset indent 347*11be35a1SLionel Sambuc<test-program> [-r resfile] [-s srcdir] [-v var=value]* <test-case>[:body] 348*11be35a1SLionel Sambuc.Ed 349*11be35a1SLionel Sambuc.Pp 350*11be35a1SLionel SambucThis must run the test case body 351*11be35a1SLionel Sambuc.Dq as is , 352*11be35a1SLionel Sambucwithout any attempt of isolating it from the rest of the system. It is the 353*11be35a1SLionel Sambucresponsibility of the runtime engine to do such isolation. 354*11be35a1SLionel Sambuc.Pp 355*11be35a1SLionel SambucThe runtime engine always passes the path of a nonexistent file to 356*11be35a1SLionel Sambuc.Fl r , 357*11be35a1SLionel Sambucwhich must be created by the test case; and always passes an absolute path 358*11be35a1SLionel Sambucto the 359*11be35a1SLionel Sambuc.Fl s 360*11be35a1SLionel Sambucflag pointing to the directory containing the test program executable. 361*11be35a1SLionel Sambuc.Pp 362*11be35a1SLionel SambucThe runtime engine shall pass any configuration variables it wants through 363*11be35a1SLionel Sambucthe 364*11be35a1SLionel Sambuc.Fl v 365*11be35a1SLionel Sambucflag, and these can be later inspected by the test case at will. 366*11be35a1SLionel Sambuc.Pp 367*11be35a1SLionel SambucA note to users: if you run the test case by hand (not through 368*11be35a1SLionel Sambuc.Xr kyua 1 nor 369*11be35a1SLionel Sambuc.Xr atf-run 1 ) 370*11be35a1SLionel Sambucfrom the command line, none of the isolation features described in the 371*11be35a1SLionel Sambucisolation section apply. This means that the test case can (and probably 372*11be35a1SLionel Sambucwill) write to the current directory and leave garbage behind. Also, given 373*11be35a1SLionel Sambucthat the test case is executed without e.g. clearing the environment, the 374*11be35a1SLionel Sambucresults of the test case may differ from those obtained when running the 375*11be35a1SLionel Sambuctest case inside the runtime engine. 376*11be35a1SLionel Sambuc.Em Only use this for debugging purposes 377*11be35a1SLionel Sambuc(i.e. to run the test case code under GDB). 378*11be35a1SLionel Sambuc.Pp 379*11be35a1SLionel SambucThe syntax to run a test case cleanup part is: 380*11be35a1SLionel Sambuc.Bd -literal -offset indent 381*11be35a1SLionel Sambuc<test-program> [-s srcdir] [-v var=value]* <test-case>:cleanup 382*11be35a1SLionel Sambuc.Ed 383*11be35a1SLionel Sambuc.Pp 384*11be35a1SLionel SambucThis can only be performed if and only if the test case sets the 385*11be35a1SLionel Sambuc.Va has.cleanup 386*11be35a1SLionel Sambucproperty to true. Otherwise the behavior of executing the cleanup part is 387*11be35a1SLionel Sambucundefined. 388*11be35a1SLionel Sambuc.Pp 389*11be35a1SLionel SambucThe same rules for 390*11be35a1SLionel Sambuc.Fl s 391*11be35a1SLionel Sambucand 392*11be35a1SLionel Sambuc.Fl v 393*11be35a1SLionel Sambucapply as to when running the body. 394*11be35a1SLionel Sambuc.Pp 395*11be35a1SLionel SambucThe cleanup part must be executed in the same directory as the body but in 396*11be35a1SLionel Sambuca separate process space. The only way for test cases to transfer state 397*11be35a1SLionel Sambuc(if any) from the body to the cleanup routine is by means of files in the 398*11be35a1SLionel Sambuccurrent directory. 399*11be35a1SLionel Sambuc.Pp 400*11be35a1SLionel SambucThe cleanup part does not have to worry about deleting temporary files 401*11be35a1SLionel Sambuccreated in the current directory. The runtime engine does this 402*11be35a1SLionel Sambucautomatically. 403*11be35a1SLionel Sambuc.Sh SEE ALSO 404*11be35a1SLionel Sambuc.Xr kyua-test 1 , 405*11be35a1SLionel Sambuc.Xr kyuafile 5 406