ATF-RUN(1)

NAME
atf-run - Kyua-based implementation of the deprecated atf-run

SYNOPSIS
atf-run [-v var=value [.. -v varN=valueN]] [test_program1 [.. test_programN]]

DESCRIPTION
DISCLAIMER: This version of atf-run provides a reimplementation of ATF's execution engine built on top of Kyua. This is a transitional script and should only be considered a helper to migrate away from ATF. Therefore, this version of atf-run mimics the behavior of the original atf-run but NOT the specific output of the command. The output of this implementation is significantly different as that of the original one. Please migrate to using ‘kyua test’ as soon as feasible. See the Migration path section below for further details.

atf-run executes a collection of test programs or, in other words, a complete test suite. The output generated by this tool is minimalistic: such output is only intended to keep track of what atf-run is doing, as the execution of a test suite can take a long time. In order to obtain detailed reports, please see the atf-report(1) utility instead.

The list of test programs to execute is read from a Kyuafile or an Atffile file present in the current directory, in this order. These files describe the test suite stored in the directory they live in, which aside from the list of test programs also includes meta-data and configuration variables. In those cases where only an Atffile exists, the atf2kyua(1) utility is used to convert the old Atffiles to new Kyuafiles in a temporary directory.

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.

The following options are available:

-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:

1.  Configuration variables defined in the system-wide configuration file shared among all test suites. This lives in ${ATF_CONFDIR}/common.conf.

2.  Configuration variables defined in the system-wide test-suite-specific configuration file. This lives in ${ATF_CONFDIR}/<test-suite>.conf.

3.  Configuration variables defined in the user-specific configuration file shared among all test suites. This lives in ${HOME}/.atf/common.conf.

4.  Configuration variables defined in the user-specific test-suite-specific configuration file. This lives in ${HOME}/.atf/<test-suite>.conf.

5.  Configuration variables provided as part of the command line through the -v option.

The value of ATF_CONFDIR in the above list is determined by the build settings of the atf-run script, but its value can be overriden by setting such variable in the environment.

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.

  Migration path
Moving from atf-run to ‘kyua test’ is rather simple.

The first step is converting all of your Atffiles to Kyuafiles. The atf2kyua(1) script will help you in performing this initial conversion.

Once all the Kyuafiles are in place, the following examples show how to convert some common atf-run invocations to their corresponding ‘kyua test’ ones.

    ### Run all tests.
    $ atf-run
    $ kyua test
    ### Run specific test programs.
    $ atf-run dir1/foo_test bar_test
    $ kyua test dir1/foo_test bar_test
    ### Set configuration variables; foo is the name of your test suite.
    $ atf-run -v unprivileged-user=nobody -v iterations=10
    $ kyua test -v unprivileged-user=nobody -v test_suite.foo.iterations=10

That said, kyua(1) is way more flexible than atf-run ever was. Please see Kyua's documentation or built-in command-line help to explore all the additional features included.

SEE ALSO
kyua(1), atf-report(1)