Skip to content

docs(skipping): warn that '&& return' breaks a conditional skip - #1214

Merged
Chemaclass merged 1 commit into
mainfrom
docs/1213-conditional-skip-return-idiom
Aug 14, 2026
Merged

docs(skipping): warn that '&& return' breaks a conditional skip#1214
Chemaclass merged 1 commit into
mainfrom
docs/1213-conditional-skip-return-idiom

Conversation

@Chemaclass

Copy link
Copy Markdown
Member

🤔 Background

Related #1213

The two skip families need opposite call shapes, and nothing said so:

function stops itself needs && return with && return when not skipping
skip no — marks only yes n/a
skip_if / skip_unless* yes (exit 0) no test ends having asserted nothing
bashunit::skip_if "[ 1 -eq 2 ]" "not met" && return   # condition false…
assert_same 1 1                                       # …yet this never runs

skip_if ends on a false if, so it returns 0, && return fires, and the
test finishes empty. It surfaces as risky rather than passing — the only
hint you get.

💡 Changes

  • Warning in docs/skipping-incomplete.md next to the conditional skips

Found by writing the idiom myself while executing the guide: three tests came
out risky instead of passing. The documented examples were already correct —
what was missing is why the shape differs.

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
@Chemaclass Chemaclass added the documentation Improvements or additions to documentation label Aug 14, 2026
@Chemaclass Chemaclass self-assigned this Aug 14, 2026
@Chemaclass
Chemaclass merged commit 13118e0 into main Aug 14, 2026
6 checks passed
@Chemaclass
Chemaclass deleted the docs/1213-conditional-skip-return-idiom branch August 14, 2026 05:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant