NIHTEST-CASE(5)

💅 NIHTEST-CASE 💅

ok so this is nihtest-case, straight out of the File Formats Manual — and yes bestie, it's the whole vibe of how .test files are written. buckle up, it's giving documentation but make it cute 🎀

---

✨ NAME ✨

nihtest-case — the test case format for nihtest, like, the actual file format you write your tests in 💖

---

🌸 DESCRIPTION 🌸

nihtest(1) is a testing tool. it eats .test files as input, and this man page is here to explain the format of those test files. that's the whole assignment 🫶

lines that start with # are comments. no cap, that's it, that's the comment rule.

here's the thing — these are the commands it recognizes. the return and args... wait no, <italic>return</italic> and <italic>args</italic>... ok so the return and arguments commands must appear exactly once, and every other one is optional. so don't be out here duplicating them, iykyk 🙈

• arguments [argument ...] — run the program with the command line arguments args. shell style quoting is supported, so you can be fancy with your quotes ✨
• description text — describes the purpose of the test. like a little caption for the group chat 📝
• directory name create [result] — describe the directory name. create and result can each be either <> if the directory is expected to exist, or {} if it isn't. create is the state before the test runs, result is the state afterwards. if result is omitted, it defaults to create — so it just assumes nothing changed 💅
• environment-clear — only variables explicitly set or passed through are included in the environment passed to the tested program. clean slate energy 🧼
• environment-passthrough variable ... — passes the named environment variables from the environment nihtest(1) is run in through to the tested program 🦋
• environment-set variable value — sets the environment variable variable to value. simple as 🍓
• environment-unset variable ... — removes the named environment variables. bye bestie 👋
• features feature ... — only run the 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. very demure, very mindful 🎀

• mkdir name — create directory name in the test directory. ⚠️ this directive is deprecated — use directory name <> instead, bestie, we're moving on 🫶
• precheck command [argument ...] — if command exits with non-zero status, skip the test. a lil vibe check before the main event ✨
• preload object — pre-load the shared object object before running the program.

this is not supported on Windows, where tests with preload will be skipped. windows said no thanks 💀

• 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. no touching 🔒
• 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. time travel, lowkey 🕰️
• 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. regex girlies rise 🔥
• 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. two very different vibes, pick one 💜

• 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. same energy, different stream 💅
• 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. main character energy, moving itself in 🧚

---

🦋 SEE ALSO 🦋

nihtest(1), nihtest-config(5) — go read your siblings, they're iconic too 💖

---

and that's the page!! brought to you by NiH, version dated May 18, 2026 — mwah, go write some slay tests 🎀✨💅