NAME
atf-run —
executes a collection of test
programs
SYNOPSIS
atf-run |
[-v var1=value1
[.. -v
varN=valueN]]
[test_program1
[..
test_programN]] |
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.
-
-
- -v
var=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 -v option.
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-run executes 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)"
}
SEE ALSO
atf-report(1),
atf-test-program(1),
atf(7)