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.
- -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}/.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/.conf
.
-
Configuration variables provided as part of the command line through the
-v
option.
The value of
ATF_CONFIG
in the above list determined as detailed in
atf-config(1).
Hooks
Ns'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(1).
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_'
that can be executed by them to invoke the default behavior built into
.
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)