feat(assert): add assert_string_matches_format assertion

Adds PHPUnit-style format assertions with placeholders:
%d (digits), %i (signed int), %f (float), %s (non-whitespace),
%x (hex), %e (scientific), %% (literal percent).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Chemaclass

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 - Add `assert_have_been_called_nth_with` assertion for verifying arguments on the Nth invocation of a spy (Issue #172)
+- Add `assert_string_matches_format` and `assert_string_not_matches_format` assertions with PHPUnit-style format placeholders (`%d`, `%s`, `%f`, `%i`, `%x`, `%e`, `%%`) (Issue #177)
 
 ### Changed
 - Split Windows CI test jobs into parallel chunks to avoid timeouts

src/assert.sh

@@ -729,3 +729,86 @@ function assert_line_count() {
 
   bashunit::state::add_assertions_passed
 }
+
+function bashunit::format_to_regex() {
+  local format="$1"
+  local regex=""
+  local i=0
+  local len=${#format}
+
+  while [ $i -lt "$len" ]; do
+    local char="${format:$i:1}"
+    if [ "$char" = "%" ] && [ $((i + 1)) -lt "$len" ]; then
+      local next="${format:$((i + 1)):1}"
+      case "$next" in
+      d) regex="${regex}[0-9]+" ;;
+      i) regex="${regex}[+-]?[0-9]+" ;;
+      f) regex="${regex}[+-]?[0-9]*\\.?[0-9]+" ;;
+      s) regex="${regex}[^ ]+" ;;
+      x) regex="${regex}[0-9a-fA-F]+" ;;
+      e) regex="${regex}[+-]?[0-9]*\\.?[0-9]+[eE][+-]?[0-9]+" ;;
+      %) regex="${regex}%" ;;
+      *)
+        regex="${regex}%${next}"
+        ;;
+      esac
+      i=$((i + 2))
+    else
+      case "$char" in
+      . | '*' | '+' | '?' | '(' | ')' | '[' | ']' | '{' | '}' | '|' | '^' | '$' | '\\')
+        regex="${regex}\\${char}"
+        ;;
+      *)
+        regex="${regex}${char}"
+        ;;
+      esac
+      i=$((i + 1))
+    fi
+  done
+
+  printf '%s' "^${regex}$"
+}
+
+function assert_string_matches_format() {
+  bashunit::assert::should_skip && return 0
+
+  local format="$1"
+  local actual="$2"
+
+  local regex
+  regex="$(bashunit::format_to_regex "$format")"
+
+  if ! [[ "$actual" =~ $regex ]]; then
+    local test_fn
+    test_fn="$(bashunit::helper::find_test_function_name)"
+    local label
+    label="$(bashunit::helper::normalize_test_function_name "$test_fn")"
+    bashunit::assert::mark_failed
+    bashunit::console_results::print_failed_test "${label}" "${actual}" "to match format" "${format}"
+    return
+  fi
+
+  bashunit::state::add_assertions_passed
+}
+
+function assert_string_not_matches_format() {
+  bashunit::assert::should_skip && return 0
+
+  local format="$1"
+  local actual="$2"
+
+  local regex
+  regex="$(bashunit::format_to_regex "$format")"
+
+  if [[ "$actual" =~ $regex ]]; then
+    local test_fn
+    test_fn="$(bashunit::helper::find_test_function_name)"
+    local label
+    label="$(bashunit::helper::normalize_test_function_name "$test_fn")"
+    bashunit::assert::mark_failed
+    bashunit::console_results::print_failed_test "${label}" "${actual}" "to not match format" "${format}"
+    return
+  fi
+
+  bashunit::state::add_assertions_passed
+}

tests/unit/assert_string_test.sh

@@ -158,3 +158,55 @@ function test_assert_string_start_end_with_special_chars_fail() {
     "Assert string start end with special chars fail" "fooX" "to end with" ".bar")" \
     "$(assert_string_ends_with ".bar" "fooX")"
 }
+
+function test_successful_assert_string_matches_format_with_digit() {
+  assert_empty "$(assert_string_matches_format "%d items found" "42 items found")"
+}
+
+function test_successful_assert_string_matches_format_with_string() {
+  assert_empty "$(assert_string_matches_format "Hello %s" "Hello world")"
+}
+
+function test_successful_assert_string_matches_format_with_hex() {
+  assert_empty "$(assert_string_matches_format "Color: %x" "Color: ff00ab")"
+}
+
+function test_successful_assert_string_matches_format_with_float() {
+  assert_empty "$(assert_string_matches_format "Value: %f" "Value: 3.14")"
+}
+
+function test_successful_assert_string_matches_format_with_signed_integer() {
+  assert_empty "$(assert_string_matches_format "Offset: %i" "Offset: -42")"
+}
+
+function test_successful_assert_string_matches_format_with_scientific() {
+  assert_empty "$(assert_string_matches_format "Result: %e" "Result: 1.5e10")"
+}
+
+function test_successful_assert_string_matches_format_with_literal_percent() {
+  assert_empty "$(assert_string_matches_format "100%% done" "100% done")"
+}
+
+function test_successful_assert_string_matches_format_with_multiple_placeholders() {
+  assert_empty "$(assert_string_matches_format "%s has %d items at %f each" "cart has 5 items at 9.99 each")"
+}
+
+function test_unsuccessful_assert_string_matches_format() {
+  assert_same \
+    "$(bashunit::console_results::print_failed_test \
+      "Unsuccessful assert string matches format" \
+      "hello world" "to match format" "%d items")" \
+    "$(assert_string_matches_format "%d items" "hello world")"
+}
+
+function test_successful_assert_string_not_matches_format() {
+  assert_empty "$(assert_string_not_matches_format "%d items" "hello world")"
+}
+
+function test_unsuccessful_assert_string_not_matches_format() {
+  assert_same \
+    "$(bashunit::console_results::print_failed_test \
+      "Unsuccessful assert string not matches format" \
+      "42 items" "to not match format" "%d items")" \
+    "$(assert_string_not_matches_format "%d items" "42 items")"
+}