No documented way to assert an exit code captured under set -e #1169

Problem

assert_successful_code, assert_unsuccessful_code, assert_general_error
and assert_command_not_found read the code from $?, and the docs say so.

Under set -e — which --strict turns on for every test — that idiom cannot be
used directly: a 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 $?, which is the assignment's 0
assert_general_error "$code"    # $1 is never read by these functions

Both silently assert the wrong thing. The second is the natural thing to write
and looks correct.

The form that works is the third argument:

assert_general_error "" "" "$code"

which is undocumented — tests/unit/benchmark/benchmark_test.sh uses it, and I
only found it by reading ${3-"$?"} in the source after writing the broken
version myself.

Fix

Document the third-argument form in all four sections. Appended at the end of
each section, because the bashunit doc renderer truncates a section and
inserting earlier silently dropped the existing assert_exec tip from CLI
output — the snapshot is unchanged with the block at the end.

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 it would silently change meaning whenever that output is a
bare integer. That is a contract change for a maintainer to make, not a docs fix.