atf-run(1) - NetBSD Manual Pages

ATF-RUN(1)              NetBSD General Commands Manual              ATF-RUN(1)


NAME

     atf-run -- executes a collection of tests


SYNOPSIS

     atf-run [-v var1=value1 [.. -v varN=valueN]] [test1 [.. testN]]
     atf-run -h


DESCRIPTION

     atf-run executes a collection of test cases, test programs, or a complete
     test suite.  The results of each test 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 vari-
     ables 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
     arguments are given as part of the command line, those tests are executed
     instead of the complete list.  Each test argument can be either the name
     of a test program, or a string of the form test_program:test_case to exe-
     cute a single test case.

     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:

     1.   Configuration variables defined in the Atffile.

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

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

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

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

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

     1.   ${ATF_CONFDIR}/atf-run.hooks

     2.   ${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)

NetBSD 10.99                    April 10, 2021                    NetBSD 10.99