atf-check —
executes a command and analyzes its results
| atf-check |
[-s
qual:value]
[-o
action:arg ...]
[-e
action:arg ...]
[-x]
command
|
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.
atf-check exits 0 on success, and other
(unspecified) value on failure.
- ATF_SHELL
- Path to the system shell to be used when the
-x is given to run commands.
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
atf-sh(1)