external/bsd/kyua-atf-compat/dist/atf-run.1

   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 :
  40 This version of
  41 .Nm
  42 provides a reimplementation of ATF's execution engine built on top of Kyua.
  43 This is a transitional script and should only be considered a helper to
  44 migrate away from ATF.
  45 Therefore, this version of
  46 .Nm
  47 mimics the
  48 .Em behavior
  49 of the original
  50 .Nm
  51 but
  52 .Em NOT
  53 the specific output of the command.
  54 The output of this implementation is significantly different as that of the
  55 original one.
  56 Please migrate to using
  57 .Sq kyua test
  58 as soon as feasible.
  59 See the
  60 .Sx Migration path
  61 section below for further details.
  62 .Pp
  63 .Nm
  64 executes a collection of test programs or, in other words, a complete
  65 test suite.
  66 The output generated by this tool is minimalistic: such output is only intended
  67 to keep track of what
  68 .Nm
  69 is doing, as the execution of a test suite can take a long time.
  70 In order to obtain detailed reports, please see the
  71 .Xr atf-report 1
  72 utility instead.
  73 .Pp
  74 The list of test programs to execute is read from a
  75 .Pa Kyuafile
  76 or an
  77 .Pa Atffile
  78 file present in the current directory, in this order.
  79 These files describe the test suite stored in the directory they live in,
  80 which aside from the list of test programs also includes meta-data and
  81 configuration variables.
  82 In those cases where only an Atffile exists, the
  83 .Xr atf2kyua 1
  84 utility is used to convert the old Atffiles to new Kyuafiles in a temporary
  85 directory.
  86 .Pp
  87 .Nm
  88 is also in charge of reading the configuration files that tune the behavior
  89 of each test program and passing down the necessary variables to them.
  90 More details on how this is done are given in the
  91 .Sx Configuration
  92 section.
  93 .Pp
  94 In the first synopsis form,
  95 .Nm
  96 parses the
  97 .Pa Atffile
  98 in the current directory and runs all the test programs specified in it.
  99 If any test program names are given as part of the command line, those are
 100 the ones executed instead of the complete list.
 101 .Pp
 102 The following options are available:
 103 .Bl -tag -width XvXvarXvalueXX
 104 .It Fl v Ar var=value
 105 Sets the configuration variable
 106 .Ar var
 107 to the given value
 108 .Ar value .
 109 .El
 110 .Ss Configuration
 111 .Nm
 112 reads configuration data from multiple places.
 113 After all of these places have been analyzed, a list of variable-value
 114 pairs are passed to the test programs to be run.
 115 .Pp
 116 The following locations are scanned for configuration data, in order.
 117 Items down the list override values defined above them:
 118 .Bl -enum
 119 .It
 120 Configuration variables defined in the system-wide configuration file
 121 shared among all test suites.
 122 This lives in
 123 .Pa ${ATF_CONFDIR}/common.conf .
 124 .It
 125 Configuration variables defined in the system-wide test-suite-specific
 126 configuration file.
 127 This lives in
 128 .Pa ${ATF_CONFDIR}/<test-suite>.conf .
 129 .It
 130 Configuration variables defined in the user-specific configuration file
 131 shared among all test suites.
 132 This lives in
 133 .Pa ${HOME}/.atf/common.conf .
 134 .It
 135 Configuration variables defined in the user-specific test-suite-specific
 136 configuration file.
 137 This lives in
 138 .Pa ${HOME}/.atf/<test-suite>.conf .
 139 .It
 140 Configuration variables provided as part of the command line through the
 141 .Fl v
 142 option.
 143 .El
 144 .Pp
 145 The value of
 146 .Va ATF_CONFDIR
 147 in the above list is determined by the build settings of the
 148 .Nm
 149 script, but its value can be overriden by setting such variable in the
 150 environment.
 151 .Pp
 152 The following configuration variables are globally recognized:
 153 .Bl -tag -width XunprivilegedXuserXX
 154 .It Va unprivileged-user
 155 The name of the system user that atf-run will drop root privileges into
 156 for test cases defining
 157 .Sq require.user=unprivileged .
 158 Note that this is
 159 .Em not provided for security purposes ;
 160 this feature is only for the convenience of the user.
 161 .El
 162 .Ss Migration path
 163 Moving from
 164 .Nm
 165 to
 166 .Sq kyua test
 167 is rather simple.
 168 .Pp
 169 The first step is converting all of your Atffiles to Kyuafiles.
 170 The
 171 .Xr atf2kyua 1
 172 script will help you in performing this initial conversion.
 173 .Pp
 174 Once all the Kyuafiles are in place, the following examples show how to
 175 convert some common
 176 .Nm
 177 invocations to their corresponding
 178 .Sq kyua test
 179 ones.
 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
 194 That said,
 195 .Xr kyua 1
 196 is way more flexible than
 197 .Nm
 198 ever was.
 199 Please see Kyua's documentation or built-in command-line help to explore
 200 all the additional features included.
 201 .Sh SEE ALSO
 202 .Xr kyua 1 ,
 203 .Xr atf-report 1