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.

directory name create [result]

Describe directory name. create and result can be either “<>” if the directory is expected to exist, or “{}” if it isn't. create specifies the state before the test is run, result the state afterwards. If result is omitted, it defaults to create.

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

mkdir name

Create directory name in the test directory. This directive is deprecated, use directory name <> instead.

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.

read-only name

The file or directory name will be made read-only.

return exit-code

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

set-modification-time file time

Set the modification of file in the sandbox to time, which can be either in ISO-8601 format or seconds since Unix epoch.

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

stdout-replace pattern replacement

Run regular expression replacement over the standard output and the expected output as provided by stdout before comparing them. See stderr-replace for details.

test-case-source filename

Use filename to refer to test case in error messages. This is useful if the test case is created by a script.

working-directory directory

Run the program in the subdirectory directory inside the sandbox. The directory will be created if it doesn't exist.

SEE ALSO

nihtest(1), nihtest-config(5)