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

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

SEE ALSO

       atf-sh(1)

Debian                                           October 5, 2014                                    ATF-CHECK(1)