#### 10.2.2 docommand

The `docommand` function runs a specified program, and checks its return value, standard output and error output against an expected version. If any mismatch occurs, `fail` is called. The `docommand` function is invoked with up to six arguments:-

    docommand [--silent] label command retval stdout stderr

The `docommand` function normally prints the label to indicate what stage the current test script has reached, followed by “done” when it has finished. The `--silent` option turns off this behaviour, so that if nothing goes wrong, no progress message is printed. This is occasionally used for commands that have already been tested by a script and are known to work, but which must be repeated several times in order to make some other kind of test, which is yet to come. I recommend you try to avoid using this option.

The other arguments to `docommand` are:-

label

  This is what is printed to indicate what is going on when the test starts. If all goes according to plan, it is followed by ‘`...done`’.

command

  This is the command to be executed, with all the required arguments.

retval

  This is the expected return value. If command exits returning any other value, `fail` will be called. If the test should not care about the return value, use ‘`IGNORE`’ as retval.

stdout

  This is the text expected on the standard output of command. If the test should not care about the standard output, use ‘`IGNORE`’ as stdout.

stderr

  This is the text expected on the error output of command. If the test should not care about the error output, use ‘`IGNORE`’ as stderr.

This command will run `admin` with three arguments, and expect it to produce no output at all and return the value zero:-

    docommand C5 "${admin} -ifoo -yMyComment $s" 0 "" ""

This command does something similar, but the command is expected to fail, returning 1 as its exit status:-

    # We should not be able to admin -i if the s-file already exists.
    docommand I7 "${admin} -ifoo $s" 1 "" IGNORE

In the example above, the error messages produced by SCCS and CSSC are different, but both indicate the same thing. However, since the messages are different, ‘`IGNORE`’ is used.

The stdout and stderr arguments are processed with the `echo_nonl` function, and so escape codes are valid and indeed heavily used:-

    # Test the -m (annotate SID) option with several deltas...
    docommand N4 "$get -p -m $s" 0 \
        "1.1\tline1\n1.1\tline2\n1.2\tline3\n" \
        IGNORE