From 3ec12e85655bda4621e092e0c712e50214c36241 Mon Sep 17 00:00:00 2001 From: Chemaclass Date: Fri, 14 Aug 2026 07:48:14 +0200 Subject: [PATCH] docs(skipping): warn that '&& return' breaks a conditional skip bashunit::skip only marks the test and execution continues, which is why it is written 'bashunit::skip "reason" && return' -- without it, one test reports both a skip and a failure. The conditional skips end in __mark_and_stop, which exits, so they need no return. Carrying the idiom across breaks them: when the condition does not hold, skip_if ends on a false 'if' and returns 0, so '&& return' fires and the test finishes having asserted nothing. It surfaces as risky rather than passing, which is the only hint. Found by writing the idiom myself while executing the guide: three tests came out risky instead of passing. The two families requiring opposite call shapes was not written down anywhere. Closes #1213 --- docs/skipping-incomplete.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/docs/skipping-incomplete.md b/docs/skipping-incomplete.md index 2bb6a415..2dc572f2 100644 --- a/docs/skipping-incomplete.md +++ b/docs/skipping-incomplete.md @@ -98,6 +98,22 @@ Called from inside a test's own `$(...)` subshell, these helpers end that subshell only — the same as any `exit`. Call them from the test body. ::: +::: warning Do not add `&& return` here +`bashunit::skip` only marks the test — execution continues, which is why it is +written `bashunit::skip "reason" && return`. The conditional skips stop the test +themselves, so they need no `return`, and adding one breaks them: + +```bash +bashunit::skip_if "[ 1 -eq 2 ]" "not met" && return # ✗ ends the test even though + # the condition did not hold +assert_same 1 1 # never runs +``` + +When the condition does not hold, `skip_if` returns `0`, so `&& return` fires and +the test finishes having asserted nothing. It is reported as **risky** rather +than passing, which is the only hint you get. +::: + ## bashunit::todo > `bashunit::todo "[pending]"`