NAME
atf-run —
executes a collection of test
programs
SYNOPSIS
atf-run |
[-v var1=value1 [..
-v varN=valueN]]
[test_program1 [..
test_programN]] |
atf-run |
-h |
DESCRIPTION
atf-run executes a collection of test programs or, in
other words, a complete test suite. The results of each test program are
collected by the tool, and are then multiplexed into a single
machine-parseable report; see
atf-formats(5) for more details. This report can later be
transformed into many different and saner formats using the
atf-report tool.
The list of test programs to execute is read from an Atffile present in the current directory. This file describes the test suite stored in the directory it lives in, which aside from the list of test programs also includes meta-data and configuration variables.
atf-run is also in charge of reading the
configuration files that tune the behavior of each test program and passing
down the necessary variables to them. More details on how this is done are
given in the Configuration
section.
In the first synopsis form, atf-run parses
the Atffile in the current directory and runs all
the test programs specified in it. If any test program names are given as
part of the command line, those are the ones executed instead of the
complete list.
In the second synopsis form, atf-run will
print information about all supported options and their purpose.
The following options are available:
-h- Shows a short summary of all available options and their purpose.
-vvar=value- Sets the configuration variable var to the given value value.
Configuration
atf-run reads configuration data from
multiple places. After all of these places have been analyzed, a list of
variable-value pairs are passed to the test programs to be run.
The following locations are scanned for configuration data, in order. Items down the list override values defined above them:
- Configuration variables defined in the Atffile.
- Configuration variables defined in the system-wide configuration file shared among all test suites. This lives in ${ATF_CONFDIR}/common.conf.
- Configuration variables defined in the system-wide test-suite-specific configuration file. This lives in ${ATF_CONFDIR}/<test-suite>.conf.
- Configuration variables defined in the user-specific configuration file shared among all test suites. This lives in ${HOME}/.atf/common.conf.
- Configuration variables defined in the user-specific test-suite-specific configuration file. This lives in ${HOME}/.atf/<test-suite>.conf.
- Configuration variables provided as part of the command line through the
-voption.
The value of ATF_CONFDIR in the above list determined as detailed in atf-config(1).
The following configuration variables are globally recognized:
- unprivileged-user
- The name of the system user that atf-run will drop root privileges into for test cases defining ‘require.user=unprivileged’. Note that this is not provided for security purposes; this feature is only for the convenience of the user.
Hooks
atf-run's internal behavior can be
customized by the system administrator and the user by means of hooks. These
hooks are written in the shell script language for simplicity and are stored
in the following files, which are read in the order provided below:
- ${ATF_CONFDIR}/atf-run.hooks
- ${HOME}/.atf/atf-run.hooks
The following hooks are supported:
- info_start_hook
- Called before
atf-runexecutes any test program. The purpose of this hook is to write additional ‘info’ stanzas to the top of the output report; these are defined by the ‘application/X-atf-tps format’ described in atf-formats(5). Always use the ‘atf_tps_writer_info’ function to print these.This takes no parameters.
- info_end_hook
- Similar to ‘info_start_hook’ but executed after all test
programs have been run so that additional ‘info’ stanzas can
be added to the bottom of the output report.
This takes no parameters.
All hooks are accompanied by a function named
‘default_<hook_name>’ that can be executed by them to
invoke the default behavior built into atf-run. For
example, in order to extend the default ‘info_start_hook’
hook, we could write the following function:
info_start_hook()
{
default_info_start_hook "${@}"
atf_tps_writer_info "uptime" "$(uptime)"
}