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