NAME

shtk_unittest_assert_command — Runs a command and validates its exit status and output

LIBRARY

shtk_import unittest

SYNOPSIS

shtk_unittest_assert_command [-e -output_spec] [-o -output_spec] [-s -exit_code_spec] command [arg1 .. argN]

DESCRIPTION

The shtk_unittest_assert_command function runs the command provided in the arguments starting at command, which can possibly refer to an in-process shell function, and verifies both its exit status and its output to stdout and stderr. If any of the checks fails, the calling test case fails as well. shtk_unittest_assert_command is the most versatile check offered by shtk_unittest(3) and should be used to validate the majority of the executions performed by test cases.

Exit checks

The -s flag can be used to specify a check on the exit status of the command and can be given more than one time. If this flag is not given, the default is to expect a successful exit; in other words, that command exits zero.

The valid values for exit_code_spec are of the form:

<exit-code>: The exit code of the command must match exit-code.
ignore: The exit code of the command is irrelevant.
exit:<exit-code>: The exit code of the command must match exit-code.
not-exit:<exit-code>: The exit code of the command must not match exit-code.
signal:<signal-number>: The command must have been terminated by signal signal-number, which can be provided both as an integer or as a name.
not-signal:<signal-number>: The command must have been terminated by a signal and the signal must not be signal-number, which can be provided both as an integer or as a name.

Output checks

The -o and -e flags can be used to specify a check on the contents of stdout or stderr, respectively, of the command. Both flags can be provided more than once to specify complementary checks on the output. If no checks are specified, the default is to expect the outputs to be empty.

The valid values for output_spec are the same as the ones described in shtk_unittest_assert_file(3).

EXAMPLES

In the simplest form, shtk_unittest_assert_command checks for success and no output so the following invocation would pass:

assert_command true

However, the following invocations would fail:

assert_command false
assert_command echo "foo"

With flags, the expectations of the executed command can be changed. For example, the following variants of the above would now pass:

assert_command -s exit:1 false
assert_command -o inline:"foo\n" echo "foo"

It is OK to specify multiple checks for a single command:

assert_command -s exit:0 -o match:foo -o match:bar -e ignore \
    echo "foo bar"

Built-in functions are also allowed as commands:

my_verbose_command() {
    echo "sent to stdout"
    echo "sent to stderr: ${*}" 1>&2
    exit 42
}

echo "sent to stderr: arg1 arg2" >experr
assert_command -s exit:42 -o inline:"sent to stdout\n" \
    -e file:experr my_verbose_command arg1 arg2

HISTORY

shtk_unittest_assert_command first appeared in shtk 1.6.