freebsd man page for atf-check

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

NAME
     atf-check -- executes a command and analyzes its results

SYNOPSIS
     atf-check [-s qual:value] [-o action:arg ...] [-e action:arg ...] [-x] command

DESCRIPTION
     atf-check executes a given command and analyzes its results, including exit code, stdout and stderr.

     Test cases must use atf-sh(3)'s atf_check builtin function instead of calling this utility directly.

     In the first synopsis form, atf-check will execute the provided command and apply checks specified by arguments.  By default it will act as
     if it was run with -s exit:0 -o empty -e empty.  Multiple checks for the same output channel are allowed and, if specified, their results
     will be combined as a logical and (meaning that the output must match all the provided checks).

     In the second synopsis form, atf-check will print information about all supported options and their purpose.

     The following options are available:

     -s qual:value  Analyzes termination status.  Must be one of:
		    exit:<value>    checks that the program exited cleanly and that its exit status is equal to value.	The exit code can be omit-
				    ted altogether, in which case any clean exit is accepted.
		    ignore	    ignores the exit check.
		    signal:<value>  checks that the program exited due to a signal and that the signal that terminated it is value.  The signal
				    can be specified both as a number or as a name, or it can also be omitted altogether, in which case any signal
				    is accepted.

		    Most of these checkers can be prefixed by the 'not-' string, which effectively reverses the check.

     -o action:arg  Analyzes standard output.  Must be one of:
		    empty	    checks that stdout is empty
		    ignore	    ignores stdout
		    file:<path>     compares stdout with given file
		    inline:<value>  compares stdout with inline value
		    match:<regexp>  looks for a regular expression in stdout
		    save:<path>     saves stdout to given file

		    Most of these checkers can be prefixed by the 'not-' string, which effectively reverses the check.

     -e action:arg  Analyzes standard error (syntax identical to above)

     -x 	    Executes command as a shell command line, executing it with the system shell defined by ATF_SHELL.	You should avoid using
		    this flag if at all possible to prevent shell quoting issues.

EXIT STATUS
     atf-check exits 0 on success, and other (unspecified) value on failure.

ENVIRONMENT
     ATF_SHELL	  Path to the system shell to be used when the -x is given to run commands.

EXAMPLES
     The following are sample invocations from within a test case.  Note that we use the atf_check function provided by atf-sh(3) instead of exe-
     cuting atf-check directly:

	   # Exit code 0, nothing on stdout/stderr
	   atf_check 'true'

	   # Typical usage if failure is expected
	   atf_check -s not-exit:0 'false'

	   # Checking stdout/stderr
	   echo foobar >expout
	   atf_check -o file:expout -e inline:"xx	yy
" 
	       'echo foobar ; printf "xx	yy
" >&2'

	   # Checking for a crash
	   atf_check -s signal:sigsegv my_program

	   # Combined checks
	   atf_check -o match:foo -o not-match:bar echo foo baz

SEE ALSO
     atf-sh(1)

BSD
								  October 5, 2014							       BSD