NIHTEST-CASE(5)

NIHTEST-CASE(5) | File Formats Manual | 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.
`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)

December 17, 2024 | NiH