docs: add assert_string_matches_format and assert_have_been_called_nth_with

Author: Chemaclass

CHANGELOG.md

@@ -3,8 +3,8 @@
 ## Unreleased
 
 ### 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)
+- Add `assert_have_been_called_nth_with` for verifying arguments on the Nth invocation of a spy
+- Add `assert_string_matches_format` and `assert_string_not_matches_format` with format placeholders (`%d`, `%s`, `%f`, `%i`, `%x`, `%e`, `%%`)
 
 ### Changed
 - Split Windows CI test jobs into parallel chunks to avoid timeouts

docs/assertions.md

@@ -221,6 +221,36 @@ function test_failure() {
 ```
 :::
 
+## assert_string_matches_format
+> `assert_string_matches_format "format" "value"`
+
+Reports an error if `value` does not match the `format` string. The format string uses PHPUnit-style placeholders:
+
+| Placeholder | Matches |
+|-------------|---------|
+| `%d` | One or more digits |
+| `%i` | Signed integer (e.g. `+1`, `-42`) |
+| `%f` | Floating point number (e.g. `3.14`) |
+| `%s` | One or more non-whitespace characters |
+| `%x` | Hexadecimal (e.g. `ff00ab`) |
+| `%e` | Scientific notation (e.g. `1.5e10`) |
+| `%%` | Literal `%` character |
+
+- [assert_string_not_matches_format](#assert-string-not-matches-format) is the inverse of this assertion and takes the same arguments.
+
+::: code-group
+```bash [Example]
+function test_success() {
+  assert_string_matches_format "%d items found" "42 items found"
+  assert_string_matches_format "%s has %d items at %f each" "cart has 5 items at 9.99 each"
+}
+
+function test_failure() {
+  assert_string_matches_format "%d items" "hello world"
+}
+```
+:::
+
 ## assert_line_count
 > `assert_line_count "count" "haystack"`
 
@@ -957,6 +987,25 @@ function test_failure() {
 ```
 :::
 
+## assert_string_not_matches_format
+> `assert_string_not_matches_format "format" "value"`
+
+Reports an error if `value` matches the `format` string. See [assert_string_matches_format](#assert-string-matches-format) for supported placeholders.
+
+- [assert_string_matches_format](#assert-string-matches-format) is the inverse of this assertion and takes the same arguments.
+
+::: code-group
+```bash [Example]
+function test_success() {
+  assert_string_not_matches_format "%d items" "hello world"
+}
+
+function test_failure() {
+  assert_string_not_matches_format "%d items" "42 items"
+}
+```
+:::
+
 ## assert_array_not_contains
 > `assert_array_not_contains "needle" "haystack"`
 

docs/test-doubles.md

@@ -174,6 +174,35 @@ function test_failure() {
 :::
 
 
+## assert_have_been_called_nth_with
+> `assert_have_been_called_nth_with "nth" "spy" "expected"`
+
+Reports an error if the `nth` invocation of `spy` was not called with `expected`. The index starts at 1. Reports an error if `spy` was called fewer than `nth` times.
+
+::: code-group
+```bash [Example]
+function test_success() {
+  bashunit::spy ps
+
+  ps first
+  ps second
+  ps third
+
+  assert_have_been_called_nth_with 1 ps "first"
+  assert_have_been_called_nth_with 2 ps "second"
+  assert_have_been_called_nth_with 3 ps "third"
+}
+
+function test_failure() {
+  bashunit::spy ps
+
+  ps first
+
+  assert_have_been_called_nth_with 1 ps "wrong"
+}
+```
+:::
+
 ## assert_have_been_called_times
 > assert_have_been_called_times "expected" "spy"