Skip to content

feat(assert): add optional custom label to assert functions (#77)#616

Merged
Chemaclass merged 2 commits intoTypedDevs:mainfrom
SauronBot:feat/77-assert-custom-label
Mar 30, 2026
Merged

feat(assert): add optional custom label to assert functions (#77)#616
Chemaclass merged 2 commits intoTypedDevs:mainfrom
SauronBot:feat/77-assert-custom-label

Conversation

@SauronBot
Copy link
Copy Markdown
Contributor

Issue

Closes #77

Background

When an assertion fails, bashunit derives the label from the test function name. In complex tests with multiple assertions on the same subject, the auto-derived label doesn't give enough context about which assertion failed or why.

PHPUnit solves this with an optional message parameter. This PR brings the same to bashunit.

Goal

Allow test authors to pass an optional trailing label to most assert functions. When provided, it replaces the auto-derived test function name in failure output.

Changes

src/assert.sh

  • Added bashunit::assert::label() helper: uses custom label if provided, falls back to find_test_function_name
  • Updated 14 fixed-arity assert functions to accept an optional last param as the label:
    assert_same, assert_equals, assert_not_equals, assert_not_same, assert_empty, assert_not_empty, assert_less_than, assert_less_or_equal_than, assert_greater_than, assert_greater_or_equal_than, assert_contains_ignore_case, assert_string_not_starts_with, assert_string_matches_format, assert_string_not_matches_format

tests/unit/assert_basic_test.sh

  • Added 4 tests verifying the custom label appears in failure output

Not supported (variadic ${@:2} or $3 already taken):
assert_contains, assert_not_contains, assert_matches, assert_not_matches, assert_string_starts_with, assert_string_ends_with, assert_string_not_ends_with, assert_line_count, exit-code assertions

Note: assert_files.sh and assert_folders.sh already support custom labels via their existing optional params — unchanged.

Example

function test_user_details() {
  local user=$(get_user 42)
  assert_same "Alice" "$(echo $user | jq -r .name)" "user name"
  assert_same "42"    "$(echo $user | jq -r .id)"   "user id"
}

Failure output:

✗ Failed:
  Expected 'Alice'
  [user name] but got 'Bob'

…TypedDevs#77)

Most assert functions now accept an optional trailing label parameter
that overrides the auto-derived test function name in failure output.

Examples:
  assert_same "expected" "$actual" "checking user name"
  assert_empty "$result" "result should be empty"
  assert_not_same "foo" "$val" "values must differ"

Affected functions in src/assert.sh:
  assert_same, assert_equals, assert_not_equals, assert_not_same,
  assert_empty, assert_not_empty,
  assert_less_than, assert_less_or_equal_than,
  assert_greater_than, assert_greater_or_equal_than,
  assert_contains_ignore_case,
  assert_string_not_starts_with,
  assert_string_matches_format, assert_string_not_matches_format

Variadic functions (assert_contains, assert_not_contains, assert_matches,
assert_not_matches, assert_string_starts_with, assert_string_ends_with,
assert_string_not_ends_with, assert_line_count) and exit-code functions
($3 already taken) do not support the label override.

Note: assert_files.sh and assert_folders.sh already supported custom
labels via their existing optional parameters.
@SauronBot SauronBot force-pushed the feat/77-assert-custom-label branch from 8a12abb to 956d493 Compare March 30, 2026 06:23
@Chemaclass Chemaclass merged commit 4b2a486 into TypedDevs:main Mar 30, 2026
26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add third optional parameter on asserts

2 participants