Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
ATF-CHECK(1)		  BSD General Commands Manual		  ATF-CHECK(1)

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

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

     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 com-
     bined as a	logical	and (meaning that the output must match	all the	pro-
     vided 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 omitted 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.

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

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

     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 executing
     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\tyy\n" \
	       'echo foobar ; printf "xx\tyy\n"	>&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


BSD				 March 6, 2017				   BSD


Want to link to this manual page? Use this URL:

home | help