DragonFly On-Line Manual Pages

SHTK_UNITTEST_ASSERT_COMMAND(3)             DragonFly Library Functions Manual

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.

DragonFly 6.5-DEVELOPMENT      November 10, 2014     DragonFly 6.5-DEVELOPMENT