From a0535ad1e2e1ed7d911755e9d4a4237f8bd8d4ae Mon Sep 17 00:00:00 2001 From: Chemaclass Date: Mon, 20 Jul 2026 01:59:16 +0200 Subject: [PATCH] docs: define the failing set_up_before_script contract MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents the behavior pinned in #838: hook failure marks every test in the file as failed, totals stay consistent, the suite continues, and a trailing `cmd && var=value` guard counts as hook failure — with the explicit-success idiom for optional-dependency skips. Claude-Session: https://claude.ai/code/session_01JSeB8UzLCpqst55hAK6dED --- docs/test-files.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/test-files.md b/docs/test-files.md index c5f7e070..624ab9cd 100644 --- a/docs/test-files.md +++ b/docs/test-files.md @@ -99,7 +99,7 @@ Running tests/example_test.sh This visibility helps identify slow setup operations that may impact test run time. -If any command inside `set_up_before_script` fails, bashunit halts the file immediately and reports the error (including the failing command and location) before any test functions run. This ensures misconfigured environments or missing dependencies surface clearly during setup. +If `set_up_before_script` fails — any failing command, or the function returning a non-zero status (watch out for a trailing `cmd && var=value` guard: when `cmd` fails, the guard is the hook's return value) — bashunit reports the hook error, marks **every test in the file as failed** (they are included in the totals), and continues with the next test file. The rest of the suite always runs, and the failure is attributed to the hook rather than surfacing as mysterious individual test errors. If you want a missing optional dependency to skip tests instead of failing them, end the hook with an explicit success, e.g. `command -v jq >/dev/null 2>&1 && HAS_JQ=true; return 0` — then call `bashunit::skip` inside the tests. ::: code-group ```bash [Example]