Skip to content

docs: add examples for newer assert helpers in README quick reference #752

Description

@tapheret2

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

  • README section with the table; every helper name in it exists in src/ (spot-check with bashunit assert <name> or grep).
  • Every example line actually passes when dropped into a test file (add them to a throwaway test locally; do not commit network/jq-dependent ones to CI without the existing jq guards).
  • Each row links to the corresponding anchor on bashunit.com/assertions.
  • make lint passes (markdown is covered by editorconfig checks).

No changes to src/ or docs/assertions.md needed — README only.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    Status
    No status

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions