NAME

nihtest-case — test case format for nihtest

DESCRIPTION

nihtest(1) is a testing tool. It uses .test files as input. This man page describes the format of these test files.

Lines beginning with “#” are comments.

The following commands are recognized. The return and args commands must appear exactly once, the others are optional.

arguments [argument ...]

Run the program with command line arguments args. Shell style quoting is supported.

description text

Describes the purpose of the test.

features feature ...

Only run test if all features are present, otherwise skip it. The features are extracted from a top-level config.h file. If the string HAVE_FOO is defined in the file, the feature FOO is assumed to be available, otherwise not. See also the description of top-build-directory in nihtest-config(5).

file name in [out]

The arguments in and out specify the contents of the file name in the test directory before and after the program is run, respectively. If out is omitted, the file is expected to remain unchanged.

“{}” specifies that the file does not exist (i. e. that it is created or deleted by the program).

For “<inline>” the contents of the file are taken from the test case, up to a line consisting of “end-of-inline-data”. If both in and out are “<inline>”, the input data comes first. Otherwise the argument specifies the name of the file to copy or compare againts.

mkdir name

Create directory name
in the test directory.

precheck command [argument ...]

If command exits with non-zero status, skip the test.

preload object

Pre-load the shared object object before running the program.

This is not supported on macOS and Windows, where tests with preload will be skipped.

program name

Run name. See the description of arguments above for its command line arguments. If this directive is omitted, default-program from nihtest.conf is run.

return exit-code

exit-code is the expected exit code (usually 0 on success).

setenv variable value

Set the environment variable variable to value.

stderr [file]

Specify the expect standard error output (stderr). If file is given, the output is compared with that file, otherwise the expected text is taken from the following lines of the test case, up to a line consisting of “end-of-inline-data”.

stderr-replace pattern replacement

Run regular expression replacement over the standard error output and the expected output as provided by stderr before comparing them. pattern is the match expression, replacement is the replacement expression. In the replacement expression, “$1” to “$9” are replaced with the content of the corresponding “(...)” match in the pattern. See re_format(7) for details.

stdin [file]

If file is given, standard input (stdin) is redirected from this file, which means the program has direct access to the file, including the ability to seek within it.

Otherwise the text provided to the program via a pipe is taken from the test case, up to a line consisting of “end-of-inline-data”.

stdout [file]

Specify the expect standard output (stdout). If file is given, the output is compared with that file, otherwise the expected text is taken from the following lines of the test case, up to a line consisting of “end-of-inline-data”.

SEE ALSO

nihtest(1), nihtest-config(5)