external/bsd/bind/dist/unit/atf-src/atf-run/atf-run.1

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