Improve how to use custom assertions

[Chemaclass]

📚 Description

Closes: #528

Improves how custom assertions display test names in failure messages by walking up the call stack to find the actual test function.

The Problem

Previously, when a custom assertion failed, the failure message would show the custom assertion's name instead of the test function name. This made it difficult to identify which test actually failed.

For example, with a custom assertion like:

function assert_valid_json() {
  local json="$1"
  if ! echo "$json" | jq . > /dev/null 2>&1; then
    fail "Invalid JSON: $json"
    return
  fi
  bashunit::assertion_passed
}

function test_api_returns_valid_json() {
  assert_valid_json "invalid"  # This fails
}

Before (confusing):

✗ Failed: Assert valid json
    Invalid JSON: invalid

After (clear):

✗ Failed: Api returns valid json
    Invalid JSON: invalid

The Solution

A new helper function helper::find_test_function_name() walks up the Bash call stack (FUNCNAME array) to find the first function that matches the test naming convention (test_* or testCamelCase). This ensures that regardless of how deeply nested the assertion is, the correct test name is always displayed.

This works for:

• Custom assertions using fail()
• Custom assertions using bashunit::assertion_failed()
• Custom assertions that compose other assertions (e.g., calling assert_same internally)
• Deeply nested function calls

🔖 Changes

• Added helper::find_test_function_name() function in src/helpers.sh that walks the call stack to find test functions
• Updated all assertion functions in src/assert.sh, src/assert_arrays.sh, src/assert_files.sh, src/assert_folders.sh, and src/assert_snapshot.sh to use the new helper
• Added comprehensive unit tests in tests/unit/custom_assertions_test.sh covering various custom assertion patterns
• Updated documentation in docs/custom-asserts.md with:
  • API reference for bashunit::assertion_failed and bashunit::assertion_passed
  • Multiple examples showing different custom assertion patterns
  • Best practices section
  • Info box explaining the automatic test name detection behavior

🖼️ Demo

🧪 Demo

fail "Invalid JSON: $json"

bashunit::assertion_failed '{"status": "ok"}' "$json"

✅ To-do list

• I updated the CHANGELOG.md to reflect the new feature or fix
• I updated the documentation to reflect the changes