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