Stop test function after first assert fails

CHANGELOG.md

@@ -16,6 +16,10 @@
     - `bashunit init [dir]` - initialize project (replaces `--init`)
     - `bashunit learn` - interactive tutorial (replaces `--learn`)
     - `bashunit upgrade` - upgrade to latest (replaces `--upgrade`)
+- **BREAKING:** Tests now stop at first assertion failure within a test function
+    - Matches PHPUnit and Jest default behavior
+    - Subsequent assertions in the same test are skipped after a failure
+    - Other test functions continue to run normally
 
 ### Fixed
 - Stop executing remaining commands in `set_up`/`tear_down` after first failure

docs/configuration.md

@@ -85,6 +85,12 @@ Force to stop the runner right after encountering one failing test. `false` by d
 
 Similar as using `-S|--stop-on-failure` option on the [command line](/command-line#stop-on-failure).
 
+::: tip Assertion behavior
+When an assertion fails within a test, subsequent assertions in the same test are automatically skipped. This matches popular testing libraries default behavior and prevents misleading failures caused by earlier assertion failures.
+
+The `--stop-on-failure` flag is separate – it stops the entire test runner after a failing **test**, while assertion-level stopping happens automatically within each test.
+:::
+
 ## Show header
 
 > `BASHUNIT_SHOW_HEADER=true|false`

docs/custom-asserts.md

@@ -6,6 +6,10 @@
 Check the internal functional tests: `tests/functional/custom_asserts_test.sh` ([link](https://github.com/TypedDevs/bashunit/blob/main/tests/functional/custom_asserts_test.sh))
 :::
 
+::: info Assertion behavior
+When using the bashunit facade, assertions automatically respect the guard behavior: if a previous assertion in the same test already failed, subsequent assertions are skipped. This matches popular testing libraries default behavior.
+:::
+
 ## assertion_failed
 > `bashunit::assertion_failed <expected> <actual> <failure_condition_message?>`