NIHTEST-CASE(5)

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.

environment-clear
    Only variables explicitly set or passed through are included in the environment passed to the tested program.

environment-passthrough variable ...
    Passes the named environment variables from the environment nihtest(1) is run in to the tested program.

environment-set variable value
    Set the environment variable variable to value.

environment-unset variable ...
    Removes the named environment variables.

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 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).

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)