1.\" Copyright 2012 Google 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 are 6.\" met: 7.\" 8.\" * Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" * Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" * Neither the name of Google Inc. nor the names of its contributors 14.\" may be used to endorse or promote products derived from this software 15.\" without specific prior written permission. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 18.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 19.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 20.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 21.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 22.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 23.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 24.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 25.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 26.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 27.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.Dd June 16, 2012 29.Dt ATF-RUN 1 30.Os 31.Sh NAME 32.Nm atf-run 33.Nd Kyua-based implementation of the deprecated atf-run 34.Sh SYNOPSIS 35.Nm 36.Op Fl v Ar var=value Op .. Fl v Ar varN=valueN 37.Op Ar test_program1 Op Ar .. test_programN 38.Sh DESCRIPTION 39.Em DISCLAIMER : 40This version of 41.Nm 42provides a reimplementation of ATF's execution engine built on top of Kyua. 43This is a transitional script and should only be considered a helper to 44migrate away from ATF. 45Therefore, this version of 46.Nm 47mimics the 48.Em behavior 49of the original 50.Nm 51but 52.Em NOT 53the specific output of the command. 54The output of this implementation is significantly different as that of the 55original one. 56Please migrate to using 57.Sq kyua test 58as soon as feasible. 59See the 60.Sx Migration path 61section below for further details. 62.Pp 63.Nm 64executes a collection of test programs or, in other words, a complete 65test suite. 66The output generated by this tool is minimalistic: such output is only intended 67to keep track of what 68.Nm 69is doing, as the execution of a test suite can take a long time. 70In order to obtain detailed reports, please see the 71.Xr atf-report 1 72utility instead. 73.Pp 74The list of test programs to execute is read from a 75.Pa Kyuafile 76or an 77.Pa Atffile 78file present in the current directory, in this order. 79These files describe the test suite stored in the directory they live in, 80which aside from the list of test programs also includes meta-data and 81configuration variables. 82In those cases where only an Atffile exists, the 83.Xr atf2kyua 1 84utility is used to convert the old Atffiles to new Kyuafiles in a temporary 85directory. 86.Pp 87.Nm 88is also in charge of reading the configuration files that tune the behavior 89of each test program and passing down the necessary variables to them. 90More details on how this is done are given in the 91.Sx Configuration 92section. 93.Pp 94In the first synopsis form, 95.Nm 96parses the 97.Pa Atffile 98in the current directory and runs all the test programs specified in it. 99If any test program names are given as part of the command line, those are 100the ones executed instead of the complete list. 101.Pp 102The following options are available: 103.Bl -tag -width XvXvarXvalueXX 104.It Fl v Ar var=value 105Sets the configuration variable 106.Ar var 107to the given value 108.Ar value . 109.El 110.Ss Configuration 111.Nm 112reads configuration data from multiple places. 113After all of these places have been analyzed, a list of variable-value 114pairs are passed to the test programs to be run. 115.Pp 116The following locations are scanned for configuration data, in order. 117Items down the list override values defined above them: 118.Bl -enum 119.It 120Configuration variables defined in the system-wide configuration file 121shared among all test suites. 122This lives in 123.Pa ${ATF_CONFDIR}/common.conf . 124.It 125Configuration variables defined in the system-wide test-suite-specific 126configuration file. 127This lives in 128.Pa ${ATF_CONFDIR}/<test-suite>.conf . 129.It 130Configuration variables defined in the user-specific configuration file 131shared among all test suites. 132This lives in 133.Pa ${HOME}/.atf/common.conf . 134.It 135Configuration variables defined in the user-specific test-suite-specific 136configuration file. 137This lives in 138.Pa ${HOME}/.atf/<test-suite>.conf . 139.It 140Configuration variables provided as part of the command line through the 141.Fl v 142option. 143.El 144.Pp 145The value of 146.Va ATF_CONFDIR 147in the above list is determined by the build settings of the 148.Nm 149script, but its value can be overriden by setting such variable in the 150environment. 151.Pp 152The following configuration variables are globally recognized: 153.Bl -tag -width XunprivilegedXuserXX 154.It Va unprivileged-user 155The name of the system user that atf-run will drop root privileges into 156for test cases defining 157.Sq require.user=unprivileged . 158Note that this is 159.Em not provided for security purposes ; 160this feature is only for the convenience of the user. 161.El 162.Ss Migration path 163Moving from 164.Nm 165to 166.Sq kyua test 167is rather simple. 168.Pp 169The first step is converting all of your Atffiles to Kyuafiles. 170The 171.Xr atf2kyua 1 172script will help you in performing this initial conversion. 173.Pp 174Once all the Kyuafiles are in place, the following examples show how to 175convert some common 176.Nm 177invocations to their corresponding 178.Sq kyua test 179ones. 180.Bd -literal -offset indent 181### Run all tests. 182$ atf-run 183$ kyua test 184 185### Run specific test programs. 186$ atf-run dir1/foo_test bar_test 187$ kyua test dir1/foo_test bar_test 188 189### Set configuration variables; foo is the name of your test suite. 190$ atf-run -v unprivileged-user=nobody -v iterations=10 191$ kyua test -v unprivileged-user=nobody -v test_suite.foo.iterations=10 192.Ed 193.Pp 194That said, 195.Xr kyua 1 196is way more flexible than 197.Nm 198ever was. 199Please see Kyua's documentation or built-in command-line help to explore 200all the additional features included. 201.Sh SEE ALSO 202.Xr kyua 1 , 203.Xr atf-report 1 204