Minix Man Pages

home | help
ATF-RUN(1)                BSD General Commands Manual               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)

BSD                              June 16, 2012                             BSD
NAME | SYNOPSIS | DESCRIPTION | SEE ALSO