SHTK_UNITTEST_ASSERT_COMMAND(3)

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

SEE ALSO
shtk(3), shtk_unittest(3)

HISTORY
shtk_unittest_assert_command first appeared in shtk 1.6.