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 45executes a collection of test programs or, in other words, a complete 46test suite. 47The results of each test program are collected by the tool, and are then 48multiplexed into a single machine-parseable report; see 49.Xr atf-formats 5 50for more details. 51This report can later be transformed into many different and saner formats 52using the 53.Nm atf-report 54tool. 55.Pp 56The list of test programs to execute is read from an 57.Pa Atffile 58present in the current directory. 59This file describes the test suite stored in the directory it lives in, 60which aside from the list of test programs also includes meta-data and 61configuration variables. 62.Pp 63.Nm 64is also in charge of reading the configuration files that tune the behavior 65of each test program and passing down the necessary variables to them. 66More details on how this is done are given in the 67.Sx Configuration 68section. 69.Pp 70In the first synopsis form, 71.Nm 72parses the 73.Pa Atffile 74in the current directory and runs all the test programs specified in it. 75If any test program names are given as part of the command line, those are 76the ones executed instead of the complete list. 77.Pp 78In the second synopsis form, 79.Nm 80will print information about all supported options and their purpose. 81.Pp 82The following options are available: 83.Bl -tag -width XvXvarXvalueXX 84.It Fl h 85Shows a short summary of all available options and their purpose. 86.It Fl v Ar var=value 87Sets the configuration variable 88.Ar var 89to the given value 90.Ar value . 91.El 92.Ss Configuration 93.Nm 94reads configuration data from multiple places. 95After all of these places have been analyzed, a list of variable-value 96pairs are passed to the test programs to be run. 97.Pp 98The following locations are scanned for configuration data, in order. 99Items down the list override values defined above them: 100.Bl -enum 101.It 102Configuration variables defined in the 103.Pa Atffile . 104.It 105Configuration variables defined in the system-wide configuration file 106shared among all test suites. 107This lives in 108.Pa ${ATF_CONFDIR}/common.conf . 109.It 110Configuration variables defined in the system-wide test-suite-specific 111configuration file. 112This lives in 113.Pa ${ATF_CONFDIR}/<test-suite>.conf . 114.It 115Configuration variables defined in the user-specific configuration file 116shared among all test suites. 117This lives in 118.Pa ${HOME}/.atf/common.conf . 119.It 120Configuration variables defined in the user-specific test-suite-specific 121configuration file. 122This lives in 123.Pa ${HOME}/.atf/<test-suite>.conf . 124.It 125Configuration variables provided as part of the command line through the 126.Fl v 127option. 128.El 129.Pp 130The value of 131.Va ATF_CONFDIR 132in the above list determined as detailed in 133.Xr atf-config 1 . 134.Pp 135The following configuration variables are globally recognized: 136.Bl -tag -width XunprivilegedXuserXX 137.It Va unprivileged-user 138The name of the system user that atf-run will drop root privileges into 139for test cases defining 140.Sq require.user=unprivileged . 141Note that this is 142.Em not provided for security purposes ; 143this feature is only for the convenience of the user. 144.El 145.Ss Hooks 146.Nm Ns 's 147internal behavior can be customized by the system administrator and the 148user by means of hooks. 149These hooks are written in the shell script language for simplicity and 150are stored in the following files, which are read in the order provided 151below: 152.Bl -enum 153.It 154${ATF_CONFDIR}/atf-run.hooks 155.It 156${HOME}/.atf/atf-run.hooks 157.El 158.Pp 159The following hooks are supported: 160.Bl -tag -width infoXstartXhookXX 161.It info_start_hook 162Called before 163.Nm 164executes any test program. 165The purpose of this hook is to write additional 166.Sq info 167stanzas to the top of the output report; these are defined by the 168.Sq application/X-atf-tps format 169described in 170.Xr atf-formats 5 . 171Always use the 172.Sq atf_tps_writer_info 173function to print these. 174.Pp 175This takes no parameters. 176.It info_end_hook 177Similar to 178.Sq info_start_hook 179but executed after all test programs have been run so that additional 180.Sq info 181stanzas can be added to the bottom of the output report. 182.Pp 183This takes no parameters. 184.El 185.Pp 186All hooks are accompanied by a function named 187.Sq default_<hook_name> 188that can be executed by them to invoke the default behavior built into 189.Nm . 190For example, in order to extend the default 191.Sq info_start_hook 192hook, we could write the following function: 193.Bd -literal -offset indent 194info_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 205