atf-test-program(1) [netbsd man page]

ATF-TEST-PROGRAM(1)					    BSD General Commands Manual 				       ATF-TEST-PROGRAM(1)

NAME

     atf-test-program -- common interface to ATF test programs

SYNOPSIS

     atf-test-program [-r resfile] [-s srcdir] [-v var1=value1 [.. -v varN=valueN]] test_case
     atf-test-program -l

DESCRIPTION

     Test programs written using the ATF libraries all share a common user interface, which is what this manual page describes.  NOTE: There is no
     binary known as atf-test-program; what is described in this manual page is the command-line interface exposed by the atf-c, atf-c++ and
     atf-sh bindings.

     In the first synopsis form, the test program will execute the provided test case and print its results to the standard output, unless other-
     wise stated by the -r flag.  Optionally, the test case name can be suffixed by ':cleanup', in which case the cleanup routine of the test case
     will be executed instead of the test case body; see atf-test-case(4).  Note that the test case is executed without isolation, so it can and
     probably will create and modify files in the current directory.  To execute test cases in a controller manner, refer to atf-run(1), which is
     the preferred way to run test cases.  You should only execute test cases by hand for debugging purposes.

     In the second synopsis form, the test program will list all available test cases alongside their meta-data properties in a format that is
     machine parseable.  This list is processed by atf-run(1) to know how to execute the test cases of a given test program.

     The following options are available:

     -l 	     Lists available test cases alongside a brief description for each of them.

     -r resfile      Specifies the file that will receive the test case result.  If not specified, the test case prints its results to stdout.	If
		     the result of a test case needs to be parsed by another program, you must use this option to redirect the result to a file
		     and then read the resulting file from the other program.  Note: do not try to process the stdout of the test case because
		     your program may break in the future.

     -s srcdir	     The path to the directory where the test program is located.  This is needed in all cases, except when the test program is
		     being executed from the current directory.  The test program will use this path to locate any helper data files or utilities.

     -v var=value    Sets the configuration variable var to the value value.

SEE ALSO

     atf-run(1), atf(7)

BSD
								 February 6, 2011							       BSD

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

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

     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-specific 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-specific 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 conve-
			   nience 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)

BSD
								 November 1, 2010							       BSD