Why
README shows a single assert_same example (README.md:51) while the framework ships ~60 assertions across 10 families. The full catalog lives in docs/assertions.md (bashunit.com/assertions) and already documents the newer helpers — the gap is purely README discoverability: someone skimming GitHub never learns that dates, durations, JSON, arrays, or file-permission asserts exist.
Proposal
Add a compact "Assertions at a glance" section to README: one row per family, one representative one-line example, link to the matching section of https://bashunit.com/assertions. Families (source of truth: src/assert*.sh):
| Family |
Example |
Equality/truth (assert_same, assert_equals, assert_true, ...) |
assert_equals "foo" "$actual" |
Strings (assert_contains, assert_matches, assert_string_starts_with, assert_line_count, ...) |
assert_string_starts_with "Hello" "$greeting" |
Exit codes (assert_exit_code, assert_successful_code, ...) |
assert_exit_code 1 "$(my_cmd)" |
Numeric (assert_greater_than, ...) |
assert_greater_than 5 "$count" |
Arrays (assert_arrays_equal, assert_array_contains, assert_array_length) |
assert_array_length 3 my_array |
Files/dirs (assert_file_exists, assert_file_permissions, assert_directory_exists, ...) |
assert_file_permissions 644 "$file" |
JSON — requires jq (assert_json_equals, assert_json_key_exists, ...) |
assert_json_contains '{"a":1}' "$json" |
Dates (assert_date_equals, assert_date_within_delta, ...) |
assert_date_before "2026-01-01" "$date" |
Duration (assert_duration_less_than, ...) |
assert_duration_less_than 200 slow_fn |
Snapshots (assert_match_snapshot, ...) |
assert_match_snapshot "$(my_cmd)" |
Test doubles (assert_have_been_called_with, ...) |
assert_have_been_called_times 2 my_fn |
Verify each example's exact signature against src/ and docs/assertions.md before committing — the table above is a sketch, not verified copy (e.g. confirm assert_array_length takes the array name vs expansion, and the assert_duration_* argument order).
Acceptance criteria
No changes to src/ or docs/assertions.md needed — README only.
Why
README shows a single
assert_sameexample (README.md:51) while the framework ships ~60 assertions across 10 families. The full catalog lives indocs/assertions.md(bashunit.com/assertions) and already documents the newer helpers — the gap is purely README discoverability: someone skimming GitHub never learns that dates, durations, JSON, arrays, or file-permission asserts exist.Proposal
Add a compact "Assertions at a glance" section to README: one row per family, one representative one-line example, link to the matching section of https://bashunit.com/assertions. Families (source of truth:
src/assert*.sh):assert_same,assert_equals,assert_true, ...)assert_equals "foo" "$actual"assert_contains,assert_matches,assert_string_starts_with,assert_line_count, ...)assert_string_starts_with "Hello" "$greeting"assert_exit_code,assert_successful_code, ...)assert_exit_code 1 "$(my_cmd)"assert_greater_than, ...)assert_greater_than 5 "$count"assert_arrays_equal,assert_array_contains,assert_array_length)assert_array_length 3 my_arrayassert_file_exists,assert_file_permissions,assert_directory_exists, ...)assert_file_permissions 644 "$file"jq(assert_json_equals,assert_json_key_exists, ...)assert_json_contains '{"a":1}' "$json"assert_date_equals,assert_date_within_delta, ...)assert_date_before "2026-01-01" "$date"assert_duration_less_than, ...)assert_duration_less_than 200 slow_fnassert_match_snapshot, ...)assert_match_snapshot "$(my_cmd)"assert_have_been_called_with, ...)assert_have_been_called_times 2 my_fnVerify each example's exact signature against
src/anddocs/assertions.mdbefore committing — the table above is a sketch, not verified copy (e.g. confirmassert_array_lengthtakes the array name vs expansion, and theassert_duration_*argument order).Acceptance criteria
src/(spot-check withbashunit assert <name>or grep).make lintpasses (markdown is covered by editorconfig checks).No changes to
src/ordocs/assertions.mdneeded — README only.