docs(assert): document how to assert a captured exit code by Chemaclass · Pull Request #1170 · TypedDevs/bashunit

Chemaclass · 2026-08-13T20:50:52Z

🤔 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 · 2026-08-13T20:50:52Z

🤔 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 · 2026-08-13T20:50:52Z

🤔 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 · 2026-08-13T20:50:52Z

🤔 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 · 2026-08-13T20:50:52Z

🤔 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 · 2026-08-13T20:50:52Z

🤔 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 · 2026-08-13T20:50:52Z

🤔 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 · 2026-08-13T20:50:52Z

🤔 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 added the documentation Improvements or additions to documentation label Aug 13, 2026