contrib/atf/atf-run/atf-run.1

   1 .\"
   2 .\" Automated Testing Framework (atf)
   3 .\"
   4 .\" Copyright (c) 2007 The NetBSD Foundation, Inc.
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND
  17 .\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  18 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  19 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20 .\" IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY
  21 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  23 .\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
  25 .\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  26 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  27 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .Dd November 1, 2010
  30 .Dt ATF-RUN 1
  31 .Os
  32 .Sh NAME
  33 .Nm atf-run
  34 .Nd executes a collection of test programs
  35 .Sh SYNOPSIS
  36 .Nm
  37 .Op Fl v Ar var1=value1 Op .. Fl v Ar varN=valueN
  38 .Op Ar test_program1 Op Ar .. test_programN
  39 .Nm
  40 .Fl h
  41 .Sh DESCRIPTION
  42 .Nm
  43 executes a collection of test programs or, in other words, a complete
  44 test suite.
  45 The results of each test program are collected by the tool, and are then
  46 multiplexed into a single machine-parseable report; see
  47 .Xr atf-formats 5
  48 for more details.
  49 This report can later be transformed into many different and saner formats
  50 using the
  51 .Nm atf-report
  52 tool.
  53 .Pp
  54 The list of test programs to execute is read from an
  55 .Pa Atffile
  56 present in the current directory.
  57 This file describes the test suite stored in the directory it lives in,
  58 which aside from the list of test programs also includes meta-data and
  59 configuration variables.
  60 .Pp
  61 .Nm
  62 is also in charge of reading the configuration files that tune the behavior
  63 of each test program and passing down the necessary variables to them.
  64 More details on how this is done are given in the
  65 .Sx Configuration
  66 section.
  67 .Pp
  68 In the first synopsis form,
  69 .Nm
  70 parses the
  71 .Pa Atffile
  72 in the current directory and runs all the test programs specified in it.
  73 If any test program names are given as part of the command line, those are
  74 the ones executed instead of the complete list.
  75 .Pp
  76 In the second synopsis form,
  77 .Nm
  78 will print information about all supported options and their purpose.
  79 .Pp
  80 The following options are available:
  81 .Bl -tag -width XvXvarXvalueXX
  82 .It Fl h
  83 Shows a short summary of all available options and their purpose.
  84 .It Fl v Ar var=value
  85 Sets the configuration variable
  86 .Ar var
  87 to the given value
  88 .Ar value .
  89 .El
  90 .Ss Configuration
  91 .Nm
  92 reads configuration data from multiple places.
  93 After all of these places have been analyzed, a list of variable-value
  94 pairs are passed to the test programs to be run.
  95 .Pp
  96 The following locations are scanned for configuration data, in order.
  97 Items down the list override values defined above them:
  98 .Bl -enum
  99 .It
 100 Configuration variables defined in the
 101 .Pa Atffile .
 102 .It
 103 Configuration variables defined in the system-wide configuration file
 104 shared among all test suites.
 105 This lives in
 106 .Pa ${ATF_CONFDIR}/common.conf .
 107 .It
 108 Configuration variables defined in the system-wide test-suite-specific
 109 configuration file.
 110 This lives in
 111 .Pa ${ATF_CONFDIR}/<test-suite>.conf .
 112 .It
 113 Configuration variables defined in the user-specific configuration file
 114 shared among all test suites.
 115 This lives in
 116 .Pa ${HOME}/.atf/common.conf .
 117 .It
 118 Configuration variables defined in the user-specific test-suite-specific
 119 configuration file.
 120 This lives in
 121 .Pa ${HOME}/.atf/<test-suite>.conf .
 122 .It
 123 Configuration variables provided as part of the command line through the
 124 .Fl v
 125 option.
 126 .El
 127 .Pp
 128 The value of
 129 .Va ATF_CONFDIR
 130 in the above list determined as detailed in
 131 .Xr atf-config 1 .
 132 .Pp
 133 The following configuration variables are globally recognized:
 134 .Bl -tag -width XunprivilegedXuserXX
 135 .It Va unprivileged-user
 136 The name of the system user that atf-run will drop root privileges into
 137 for test cases defining
 138 .Sq require.user=unprivileged .
 139 Note that this is
 140 .Em not provided for security purposes ;
 141 this feature is only for the convenience of the user.
 142 .El
 143 .Ss Hooks
 144 .Nm Ns 's
 145 internal behavior can be customized by the system administrator and the
 146 user by means of hooks.
 147 These hooks are written in the shell script language for simplicity and
 148 are stored in the following files, which are read in the order provided
 149 below:
 150 .Bl -enum
 151 .It
 152 ${ATF_CONFDIR}/atf-run.hooks
 153 .It
 154 ${HOME}/.atf/atf-run.hooks
 155 .El
 156 .Pp
 157 The following hooks are supported:
 158 .Bl -tag -width infoXstartXhookXX
 159 .It info_start_hook
 160 Called before
 161 .Nm
 162 executes any test program.
 163 The purpose of this hook is to write additional
 164 .Sq info
 165 stanzas to the top of the output report; these are defined by the
 166 .Sq application/X-atf-tps format
 167 described in
 168 .Xr atf-formats 5 .
 169 Always use the
 170 .Sq atf_tps_writer_info
 171 function to print these.
 172 .Pp
 173 This takes no parameters.
 174 .It info_end_hook
 175 Similar to
 176 .Sq info_start_hook
 177 but executed after all test programs have been run so that additional
 178 .Sq info
 179 stanzas can be added to the bottom of the output report.
 180 .Pp
 181 This takes no parameters.
 182 .El
 183 .Pp
 184 All hooks are accompanied by a function named
 185 .Sq default_<hook_name>
 186 that can be executed by them to invoke the default behavior built into
 187 .Nm .
 188 For example, in order to extend the default
 189 .Sq info_start_hook
 190 hook, we could write the following function:
 191 .Bd -literal -offset indent
 192 info_start_hook()
 193 {
 194     default_info_start_hook "${@}"
 195
 196     atf_tps_writer_info "uptime" "$(uptime)"
 197 }
 198 .Ed
 199 .Sh SEE ALSO
 200 .Xr atf-report 1 ,
 201 .Xr atf-test-program 1 ,
 202 .Xr atf 7