Skip to content

docs(assert): document how to assert a captured exit code - #1170

Merged
Chemaclass merged 1 commit into
mainfrom
docs/1169-exit-code-capture
Aug 13, 2026
Merged

Chemaclass merged 1 commit into
mainfrom
docs/1169-exit-code-capture

Conversation

@Chemaclass

Copy link
Copy Markdown
Member

🤔 Background

Related #1169

The exit-code assertions read $?. Under set -e — which --strict turns on
for every test — that idiom cannot be used directly: the non-zero exit aborts
the test before the assertion runs, so the code has to be captured, and
capturing it sets $? to zero.

local code=0
some_command || code=$?

assert_general_error            # reads $?, the assignment's 0
assert_general_error "$code"    # $1 is never read by these functions

Both silently assert the wrong thing, and the second is the natural spelling.
The working form — assert_general_error "" "" "$code" — was undocumented.

💡 Changes

  • Document the third-argument form in all four sections, noting that assert_exit_code takes its expected code in $1
  • Appended at the end of each section: the bashunit doc renderer truncates a section, and inserting earlier silently dropped the existing assert_exec tip from CLI output. With the block at the end the doc snapshot is byte-identical

Not changing

Making $1 the captured code would fix the natural spelling, but
assert_general_error "$(some_cmd)" is an established idiom in this repo that
relies on $? and would silently change meaning for numeric output. That is a
contract change for a maintainer.

assert_successful_code, assert_unsuccessful_code, assert_general_error and
assert_command_not_found read $?. Under set -e -- which --strict turns on for
every test -- that cannot be used directly: the non-zero exit aborts the test
before the assertion runs, so the code must be captured, and capturing it sets
$? to zero. Both

  assert_general_error
  assert_general_error "$code"

then assert the wrong thing silently, the second being the natural spelling.
The working form takes the code as the third argument, and was undocumented.

Appended at the end of each section rather than after the intro line: the
`bashunit doc` renderer truncates a section, so inserting earlier dropped the
existing assert_exec tip from CLI output. With the block at the end the doc
snapshot is byte-identical.

Not changing $1 to mean the captured code: assert_general_error "$(cmd)" is an
established idiom here that relies on $?, and it would silently change meaning
whenever that output is a bare integer.

Closes #1169
@Chemaclass Chemaclass added the documentation Improvements or additions to documentation label Aug 13, 2026
@Chemaclass Chemaclass self-assigned this Aug 13, 2026
@Chemaclass
Chemaclass merged commit 819ed8b into main Aug 13, 2026
6 checks passed
@Chemaclass
Chemaclass deleted the docs/1169-exit-code-capture branch August 13, 2026 20:57
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