From e1a03e5ba3d755123a371b96447e0d2d584cebb7 Mon Sep 17 00:00:00 2001
From: Chemaclass <chemaclass@outlook.es>
Date: Wed, 29 Jul 2026 07:09:03 +0200
Subject: [PATCH] feat(assert): bashunit::assert_once makes a composed
 assertion report once

A custom assertion built out of built-in assertions counts one assertion per
inner step, and its failure names that step rather than the check the test
author wrote. `assert_http_success` composed from two comparisons reported 2
assertions per call and failed with "Expected '500' to be less than '300'".

Add an opt-in marker: `bashunit::assert_once <label> <actual>` at the top of a
custom assertion absorbs everything it asserts into a single reported
assertion, labelled with the test that called it.

The issue proposed an implicit nesting-depth counter. That does not work here:
the inner assertions are siblings, not nested frames -- the first has already
returned when the second starts, so both read depth 0. What distinguishes
composed from direct is an enclosing assert_* frame, and detecting that
implicitly would classify the inner assertion of assert_assertion_fails (#916)
as nested, silencing the very counters its verdict detection reads. An implicit
rule would also shift the totals of every suite already composing assertions.

Bash gives no cheap hook on a user function's return, so the marker counts one
passing assertion immediately and the flush converts it to a failure if
anything it absorbed failed. Totals are therefore correct at every point in
time without ever observing the declaring frame return. The marker is settled
by the next assert_once call (which is what makes a loop count once per
iteration), by an assertion reached after the declaring frame returned, or by
the end of the test.

The end-of-test flush runs from the EXIT trap, where the test frame is gone, so
the label is resolved eagerly at declaration time; otherwise failures were
reported as "Bashunit::assert::once flush".

Absorption hooks live in state::add_assertions_passed, assert::mark_failed,
console_results::print_failed_test and ::print_failure_message, each behind a
plain global test so the per-assertion path stays flat. assert::_capture saves
and restores the whole marker so #916 keeps working around it.

Closes #917
---
 CHANGELOG.md                                  |   1 +
 docs/custom-asserts.md                        |  54 ++++++
 docs/globals.md                               |   2 +
 src/assert.sh                                 |   9 +
 src/assert_assertions.sh                      |  28 ++++
 src/assert_once.sh                            | 156 ++++++++++++++++++
 src/assertions.sh                             |   1 +
 src/console_results.sh                        |  18 ++
 src/runner.sh                                 |   4 +
 src/state.sh                                  |   6 +
 tests/acceptance/bashunit_assert_once_test.sh |  40 +++++
 .../fixtures/test_assert_once_composed.sh     |  29 ++++
 tests/unit/assert_once_test.sh                |  98 +++++++++++
 13 files changed, 446 insertions(+)
 create mode 100644 src/assert_once.sh
 create mode 100644 tests/acceptance/bashunit_assert_once_test.sh
 create mode 100644 tests/acceptance/fixtures/test_assert_once_composed.sh
 create mode 100644 tests/unit/assert_once_test.sh

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 39221f0f..438cb8cf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -3,6 +3,7 @@
 ## Unreleased
 
 ### Added
+- `bashunit::assert_once <label> <actual>` makes a composed custom assertion count and report once instead of once per inner step, with its own label rather than the internal step's message. Opt-in, so existing totals are unchanged (#917)
 - `assert_assertion_passes`, `assert_assertion_fails` and `assert_assertion_fails_with <message>` test a custom assertion for the verdict it reports. The inner assertion runs isolated — its counters, output and stop-on-failure guard are restored — so testing a failing assertion no longer means rebuilding the expected string from `bashunit::console_results::print_failed_test` (#916)
 - `bashunit::assert_that <expected> <actual> <cmd> [args...]` writes a custom assertion in one call: it runs the command and marks the assertion passed or failed, so the two counters can no longer drift apart by a forgotten `return` or a missing `bashunit::assertion_passed` (#915)
 - `bashunit::assertion_failed` takes an optional 4th argument labelling the failure block, so a custom assertion can name itself instead of showing the test name (#915)
diff --git a/docs/custom-asserts.md b/docs/custom-asserts.md
index d7b2eddd..d8c8c7d8 100644
--- a/docs/custom-asserts.md
+++ b/docs/custom-asserts.md
@@ -36,6 +36,18 @@ Returns `0` when the command succeeds and `1` when it fails, so it can be chaine
 The command is invoked directly, without `eval`, so arguments keep their word
 boundaries and nothing is re-parsed by the shell.
 
+### assert_once
+> `bashunit::assert_once <label?> <actual?>`
+
+Declares that the calling custom assertion counts and reports as **one**
+assertion, whatever it asserts internally. See
+[Composing with existing assertions](#composing-with-existing-assertions).
+
+| Parameter | Description |
+|-----------|-------------|
+| `label` | What the assertion expects, shown in the failure block. Omit it to report the innermost failure message instead |
+| `actual` | The actual value shown against that label |
+
 ### assertion_failed
 > `bashunit::assertion_failed <expected> <actual> <failure_condition_message?> <label?>`
 
@@ -168,6 +180,48 @@ function test_api_returns_success() {
 }
 ```
 
+By default each inner assertion is counted and reported on its own, so one call
+to `assert_http_success` counts as two assertions and a failure reads
+`Expected '500' to be less than '300'` — the internal step rather than "not an
+HTTP success".
+
+Add `bashunit::assert_once` at the top to report the whole thing as one:
+
+```bash
+function assert_http_success() {
+  bashunit::assert_once "a 2xx status" "$1"
+
+  assert_greater_or_equal_than "200" "$1"
+  assert_less_than "300" "$1"
+}
+```
+
+```
+Tests:      1 passed, 1 failed, 2 total
+Assertions: 1 passed, 1 failed, 2 total
+```
+
+The failure now reads `Expected 'a 2xx status' but got '500'`, labelled with the
+test that called it.
+
+| Parameter | Description |
+|-----------|-------------|
+| `label` | What the assertion expects, shown in the failure block. Omit it to keep reporting the innermost failure message |
+| `actual` | The actual value shown against that label |
+
+Notes:
+
+- It is opt-in. A composed assertion without the marker keeps counting and
+  reporting exactly as before.
+- Every call counts, including repeated calls from a loop.
+- The inner assertions all run even when one fails, so the marker reports on the
+  whole check rather than stopping at the first step.
+- The marker is settled when the custom assertion is called again, when an
+  assertion runs after it returned, or at the end of the test — whichever comes
+  first.
+- `bashunit::assert_that` (above) is the shorter option when the check is a
+  single command rather than several composed assertions.
+
 ### Custom assertion with custom failure message
 
 ```bash
diff --git a/docs/globals.md b/docs/globals.md
index 11813e9e..6deb3101 100644
--- a/docs/globals.md
+++ b/docs/globals.md
@@ -91,6 +91,8 @@ These helpers are intended for building [custom assertions](/custom-asserts).
 
 - `bashunit::assert_that <expected> <actual> <cmd> [args...]` — Run `cmd` and mark
   the assertion passed or failed accordingly, in a single call.
+- `bashunit::assert_once <?label> <?actual>` — Declare that the calling custom
+  assertion counts and reports once, whatever it asserts internally.
 - `bashunit::assertion_passed` — Mark the current assertion as passed.
 - `bashunit::assertion_failed <expected> <actual> <?failure_condition_message> <?label>`
   — Mark the current assertion as failed and print a failure report. `label`
diff --git a/src/assert.sh b/src/assert.sh
index 16a2352a..fafcceee 100755
--- a/src/assert.sh
+++ b/src/assert.sh
@@ -2,6 +2,15 @@
 
 # Helper to mark assertion as failed and set the guard flag
 function bashunit::assert::mark_failed() {
+  # While a bashunit::assert_once marker absorbs this assertion, neither the
+  # counter nor the guard moves: the marker's flush reports the single verdict,
+  # and leaving the guard clear lets the rest of the composed assertion run.
+  if [ "${_BASHUNIT_ASSERT_ONCE_ACTIVE:-0}" -eq 1 ]; then
+    if bashunit::assert::once_is_absorbing; then
+      _BASHUNIT_ASSERT_ONCE_FAILED=1
+      return 0
+    fi
+  fi
   bashunit::state::add_assertions_failed
   bashunit::state::mark_assertion_failed_in_test
 }
diff --git a/src/assert_assertions.sh b/src/assert_assertions.sh
index 7e12f417..2322288a 100644
--- a/src/assert_assertions.sh
+++ b/src/assert_assertions.sh
@@ -41,12 +41,30 @@ function bashunit::assert::_capture() {
   local before_output=$_BASHUNIT_TEST_OUTPUT
   local before_count=$_BASHUNIT_TOTAL_TESTS_COUNT
 
+  # A bashunit::assert_once marker open around this call would swallow the very
+  # verdict the counters below are read for, so it is set aside for the
+  # duration and restored afterwards.
+  local before_once_active=$_BASHUNIT_ASSERT_ONCE_ACTIVE
+  local before_once_frame=$_BASHUNIT_ASSERT_ONCE_FRAME
+  local before_once_abs=$_BASHUNIT_ASSERT_ONCE_ABS
+  local before_once_label=$_BASHUNIT_ASSERT_ONCE_LABEL
+  local before_once_actual=$_BASHUNIT_ASSERT_ONCE_ACTUAL
+  local before_once_failed=$_BASHUNIT_ASSERT_ONCE_FAILED
+  local before_once_in_expected=$_BASHUNIT_ASSERT_ONCE_IN_EXPECTED
+  local before_once_in_condition=$_BASHUNIT_ASSERT_ONCE_IN_CONDITION
+  local before_once_in_actual=$_BASHUNIT_ASSERT_ONCE_IN_ACTUAL
+  bashunit::assert::once_reset
+
   # Run the inner assertion unguarded: had an earlier assertion in this test
   # failed, it would otherwise skip and report no verdict at all.
   _BASHUNIT_ASSERTION_FAILED_IN_TEST=0
 
   "$@" >/dev/null 2>&1 || true
 
+  # Settle a marker the captured assertion opened, so its single verdict is
+  # visible in the counters read below.
+  bashunit::assert::once_flush >/dev/null 2>&1
+
   bashunit::str::strip_ansi_to_slot "${_BASHUNIT_TEST_OUTPUT#"$before_output"}"
   local output=$_BASHUNIT_STR_STRIPPED_OUT
 
@@ -69,6 +87,16 @@ function bashunit::assert::_capture() {
   _BASHUNIT_ASSERTION_FAILED_IN_TEST=$before_guard
   _BASHUNIT_TEST_OUTPUT=$before_output
   _BASHUNIT_TOTAL_TESTS_COUNT=$before_count
+
+  _BASHUNIT_ASSERT_ONCE_FRAME=$before_once_frame
+  _BASHUNIT_ASSERT_ONCE_ABS=$before_once_abs
+  _BASHUNIT_ASSERT_ONCE_LABEL=$before_once_label
+  _BASHUNIT_ASSERT_ONCE_ACTUAL=$before_once_actual
+  _BASHUNIT_ASSERT_ONCE_FAILED=$before_once_failed
+  _BASHUNIT_ASSERT_ONCE_IN_EXPECTED=$before_once_in_expected
+  _BASHUNIT_ASSERT_ONCE_IN_CONDITION=$before_once_in_condition
+  _BASHUNIT_ASSERT_ONCE_IN_ACTUAL=$before_once_in_actual
+  _BASHUNIT_ASSERT_ONCE_ACTIVE=$before_once_active
 }
 
 _BASHUNIT_ASSERT_INNER_OUTCOME_OUT=""
diff --git a/src/assert_once.sh b/src/assert_once.sh
new file mode 100644
index 00000000..df5ef30f
--- /dev/null
+++ b/src/assert_once.sh
@@ -0,0 +1,156 @@
+#!/usr/bin/env bash
+
+# Opt-in marker letting a composed custom assertion count and report once.
+#
+# A custom assertion built out of built-in assertions otherwise reports one
+# assertion per inner step, and its failure names the inner step rather than
+# itself. Declaring bashunit::assert_once at the top of such a function absorbs
+# every assertion it makes into a single reported one.
+#
+# Why opt-in: bash gives no cheap hook on a user function's *return*, and the
+# inner assertions are siblings rather than nested frames, so there is nothing
+# to detect implicitly without a functrace RETURN trap on the per-test hot path.
+# An explicit marker also keeps existing suites' totals unchanged.
+#
+# How the absence of a return hook is worked around: the marker counts one
+# passing assertion immediately, and the flush converts that into a failure if
+# any absorbed assertion failed. The totals are therefore correct at every point
+# in time, without ever needing to observe the declaring function returning.
+#
+# The marker is closed (flushed) by whichever of these happens first:
+#   - another bashunit::assert_once call, which is what makes a loop over the
+#     same custom assertion count once per iteration,
+#   - an assertion reached after the declaring frame has returned,
+#   - the end of the test, via bashunit::runner::cleanup_on_exit.
+
+_BASHUNIT_ASSERT_ONCE_ACTIVE=0
+_BASHUNIT_ASSERT_ONCE_FRAME=""
+_BASHUNIT_ASSERT_ONCE_ABS=0
+_BASHUNIT_ASSERT_ONCE_LABEL=""
+_BASHUNIT_ASSERT_ONCE_ACTUAL=""
+_BASHUNIT_ASSERT_ONCE_FAILED=0
+_BASHUNIT_ASSERT_ONCE_IN_EXPECTED=""
+_BASHUNIT_ASSERT_ONCE_IN_CONDITION=""
+_BASHUNIT_ASSERT_ONCE_IN_ACTUAL=""
+# Name of the test that opened the marker, resolved while its frame is still on
+# the stack. The end-of-test flush runs from the EXIT trap, where it is not.
+_BASHUNIT_ASSERT_ONCE_TEST_LABEL=""
+
+##
+# Whether an inner assertion should be absorbed by an open marker right now.
+# Closes the marker when the frame that declared it has already returned.
+# Returns: 0 while absorbing, 1 otherwise
+##
+function bashunit::assert::once_is_absorbing() {
+  [ "$_BASHUNIT_ASSERT_ONCE_ACTIVE" -eq 1 ] || return 1
+
+  # The declaring frame was recorded by its distance from the bottom of the
+  # stack, so the lookup stays valid however deep the inner assertions nest.
+  local index=$((${#FUNCNAME[@]} - _BASHUNIT_ASSERT_ONCE_ABS))
+  if [ "$index" -ge 0 ] &&
+    [ "${FUNCNAME[$index]-}" = "$_BASHUNIT_ASSERT_ONCE_FRAME" ]; then
+    return 0
+  fi
+
+  bashunit::assert::once_flush
+  return 1
+}
+
+##
+# Records the first absorbed failure message, kept as the fallback for a marker
+# that declared no label of its own.
+# Arguments: $1 - expected, $2 - failure condition message, $3 - actual
+##
+function bashunit::assert::once_absorb_message() {
+  _BASHUNIT_ASSERT_ONCE_FAILED=1
+
+  if [ -n "$_BASHUNIT_ASSERT_ONCE_IN_EXPECTED$_BASHUNIT_ASSERT_ONCE_IN_ACTUAL" ]; then
+    return 0
+  fi
+
+  _BASHUNIT_ASSERT_ONCE_IN_EXPECTED=${1-}
+  _BASHUNIT_ASSERT_ONCE_IN_CONDITION=${2-}
+  _BASHUNIT_ASSERT_ONCE_IN_ACTUAL=${3-}
+}
+
+##
+# Settles an open marker: reports its single failure if anything it absorbed
+# failed, otherwise leaves the optimistic pass counted at declaration time.
+# Safe to call with no marker open.
+##
+function bashunit::assert::once_flush() {
+  [ "$_BASHUNIT_ASSERT_ONCE_ACTIVE" -eq 1 ] || return 0
+
+  # Close first: the reporting below goes through the ordinary assertion
+  # machinery and must not be absorbed by the marker it is closing.
+  _BASHUNIT_ASSERT_ONCE_ACTIVE=0
+
+  if [ "$_BASHUNIT_ASSERT_ONCE_FAILED" -eq 0 ]; then
+    return 0
+  fi
+
+  # Undo the optimistic pass taken at declaration time.
+  _BASHUNIT_ASSERTIONS_PASSED=$((_BASHUNIT_ASSERTIONS_PASSED - 1))
+
+  local expected=$_BASHUNIT_ASSERT_ONCE_LABEL
+  local condition="but got "
+  local actual=$_BASHUNIT_ASSERT_ONCE_ACTUAL
+
+  # With no label of its own, fall back to the innermost failure, which is
+  # exactly what bashunit reports today.
+  if [ -z "$expected" ]; then
+    expected=$_BASHUNIT_ASSERT_ONCE_IN_EXPECTED
+    condition=$_BASHUNIT_ASSERT_ONCE_IN_CONDITION
+    actual=$_BASHUNIT_ASSERT_ONCE_IN_ACTUAL
+  fi
+
+  bashunit::assert::fail_with \
+    "$_BASHUNIT_ASSERT_ONCE_TEST_LABEL" "$expected" "$condition" "$actual"
+}
+
+# Clears any marker so it cannot leak from one test into the next.
+function bashunit::assert::once_reset() {
+  _BASHUNIT_ASSERT_ONCE_ACTIVE=0
+  _BASHUNIT_ASSERT_ONCE_FRAME=""
+  _BASHUNIT_ASSERT_ONCE_ABS=0
+  _BASHUNIT_ASSERT_ONCE_LABEL=""
+  _BASHUNIT_ASSERT_ONCE_ACTUAL=""
+  _BASHUNIT_ASSERT_ONCE_FAILED=0
+  _BASHUNIT_ASSERT_ONCE_IN_EXPECTED=""
+  _BASHUNIT_ASSERT_ONCE_IN_CONDITION=""
+  _BASHUNIT_ASSERT_ONCE_IN_ACTUAL=""
+  _BASHUNIT_ASSERT_ONCE_TEST_LABEL=""
+}
+
+##
+# Declares that the calling custom assertion counts and reports as one
+# assertion, whatever it asserts internally.
+# Arguments: $1 - label shown in the failure block (optional; without it the
+#                 innermost failure message is reported, as it is today),
+#            $2 - actual value shown against that label (optional)
+##
+function bashunit::assert_once() {
+  bashunit::assert::should_skip && return 0
+
+  # Settle a marker left open by a sibling call or by the previous iteration of
+  # a loop over the same custom assertion.
+  bashunit::assert::once_flush
+
+  bashunit::assert::once_reset
+
+  _BASHUNIT_ASSERT_ONCE_LABEL=${1-}
+  _BASHUNIT_ASSERT_ONCE_ACTUAL=${2-}
+
+  # Count now, convert on flush: see the note at the top of this file.
+  bashunit::state::add_assertions_passed
+
+  # Resolved here, while the test frame is still on the stack: the end-of-test
+  # flush runs from the EXIT trap, which would otherwise label the failure with
+  # the flushing function's own name.
+  bashunit::assert::label_to_slot ""
+  _BASHUNIT_ASSERT_ONCE_TEST_LABEL=$_BASHUNIT_ASSERT_LABEL_OUT
+
+  _BASHUNIT_ASSERT_ONCE_FRAME=${FUNCNAME[1]-}
+  _BASHUNIT_ASSERT_ONCE_ABS=$((${#FUNCNAME[@]} - 1))
+  _BASHUNIT_ASSERT_ONCE_ACTIVE=1
+}
diff --git a/src/assertions.sh b/src/assertions.sh
index 2c09d5a4..9d2bdde2 100644
--- a/src/assertions.sh
+++ b/src/assertions.sh
@@ -3,6 +3,7 @@
 source "$BASHUNIT_ROOT_DIR/src/assert.sh"
 source "$BASHUNIT_ROOT_DIR/src/assert_arrays.sh"
 source "$BASHUNIT_ROOT_DIR/src/assert_assertions.sh"
+source "$BASHUNIT_ROOT_DIR/src/assert_once.sh"
 source "$BASHUNIT_ROOT_DIR/src/assert_dates.sh"
 source "$BASHUNIT_ROOT_DIR/src/assert_duration.sh"
 source "$BASHUNIT_ROOT_DIR/src/assert_files.sh"
diff --git a/src/console_results.sh b/src/console_results.sh
index a17a6bf3..ab2fea9e 100644
--- a/src/console_results.sh
+++ b/src/console_results.sh
@@ -279,6 +279,14 @@ function bashunit::console_results::print_failure_message() {
   local test_name=$1
   local failure_message=$2
 
+  # Absorbed by an open bashunit::assert_once marker: see print_failed_test.
+  if [ "${_BASHUNIT_ASSERT_ONCE_ACTIVE:-0}" -eq 1 ]; then
+    if bashunit::assert::once_is_absorbing; then
+      bashunit::assert::once_absorb_message "$failure_message" "" ""
+      return 0
+    fi
+  fi
+
   local line
   line="$(printf "\
 ${_BASHUNIT_COLOR_FAILED}✗ Failed${_BASHUNIT_COLOR_DEFAULT}: %s
@@ -344,6 +352,16 @@ function bashunit::console_results::print_failed_test() {
   # caller). The spy assertions use it to dump the recorded call log.
   local details=${7-}
 
+  # Absorbed by an open bashunit::assert_once marker: keep the message as the
+  # no-label fallback and print nothing, so the composed assertion reports once.
+  if [ "${_BASHUNIT_ASSERT_ONCE_ACTIVE:-0}" -eq 1 ]; then
+    if bashunit::assert::once_is_absorbing; then
+      bashunit::assert::once_absorb_message "$expected" \
+        "$failure_condition_message" "$actual"
+      return 0
+    fi
+  fi
+
   # For multiline values, render a unified diff below the header (git required,
   # opt out with BASHUNIT_NO_DIFF). Single-line output stays byte-identical.
   local show_diff=false
diff --git a/src/runner.sh b/src/runner.sh
index a0dbf75a..463adcf0 100755
--- a/src/runner.sh
+++ b/src/runner.sh
@@ -1461,6 +1461,10 @@ function bashunit::runner::cleanup_on_exit() {
 
   set +e
 
+  # Settle a bashunit::assert_once marker the test body left open, before
+  # tear_down runs its own assertions and before the counters are exported.
+  bashunit::assert::once_flush
+
   # Detect unexpected subshell exit during set_up (Issue #611).
   # When 'source' of a non-existent file fails under set -eE, the ERR trap
   # does not fire. On macOS Bash 3.2, $? is 0 in the EXIT trap; on Linux
diff --git a/src/state.sh b/src/state.sh
index a1e523c0..72426c40 100644
--- a/src/state.sh
+++ b/src/state.sh
@@ -92,6 +92,11 @@ function bashunit::state::get_assertions_passed() {
 }
 
 function bashunit::state::add_assertions_passed() {
+  # Cheap global test first: the function call only happens while a
+  # bashunit::assert_once marker is open, keeping the per-assertion path flat.
+  if [ "${_BASHUNIT_ASSERT_ONCE_ACTIVE:-0}" -eq 1 ]; then
+    bashunit::assert::once_is_absorbing && return 0
+  fi
   ((_BASHUNIT_ASSERTIONS_PASSED++)) || true
 }
 
@@ -204,6 +209,7 @@ function bashunit::state::initialize_assertions_count() {
   _BASHUNIT_TEST_HOOK_FAILURE=""
   _BASHUNIT_TEST_HOOK_MESSAGE=""
   _BASHUNIT_ASSERTION_FAILED_IN_TEST=0
+  bashunit::assert::once_reset
 }
 
 # base64-encodes a field, writing the result into _BASHUNIT_STATE_ENCODED_OUT.
diff --git a/tests/acceptance/bashunit_assert_once_test.sh b/tests/acceptance/bashunit_assert_once_test.sh
new file mode 100644
index 00000000..3167a46a
--- /dev/null
+++ b/tests/acceptance/bashunit_assert_once_test.sh
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+
+FIXTURE="tests/acceptance/fixtures/test_assert_once_composed.sh"
+TEST_ENV_FILE="tests/acceptance/fixtures/.env.default"
+
+function fixture_summary() {
+  ./bashunit --no-parallel --no-color --env "$TEST_ENV_FILE" "$FIXTURE" 2>&1 || true
+}
+
+function test_a_composed_assertion_counts_once_per_call() {
+  local output
+  output=$(fixture_summary)
+
+  # 6 calls to assert_http_success (1 + 1 + 3 in the loop + 1) plus the one
+  # plain assert_same, instead of the 13 the inner built-ins would count alone.
+  assert_contains "6 passed" "$output"
+  assert_contains "1 failed, 7 total" "$output"
+}
+
+function test_a_composed_failure_reports_the_custom_label() {
+  local output
+  output=$(fixture_summary)
+
+  assert_contains "Expected 'a 2xx status'" "$output"
+  assert_contains "but got  '500'" "$output"
+}
+
+function test_a_composed_failure_is_named_after_the_test_not_the_flush() {
+  local output
+  output=$(fixture_summary)
+
+  assert_contains "Failed: Composed fails" "$output"
+}
+
+function test_a_composed_failure_hides_the_inner_assertion_message() {
+  local output
+  output=$(fixture_summary)
+
+  assert_not_contains "to be less than" "$output"
+}
diff --git a/tests/acceptance/fixtures/test_assert_once_composed.sh b/tests/acceptance/fixtures/test_assert_once_composed.sh
new file mode 100644
index 00000000..f0145524
--- /dev/null
+++ b/tests/acceptance/fixtures/test_assert_once_composed.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+
+# A composed custom assertion that opts in to being counted and reported once.
+function assert_http_success() {
+  bashunit::assert_once "a 2xx status" "$1"
+
+  assert_greater_or_equal_than "200" "$1"
+  assert_less_than "300" "$1"
+}
+
+function test_composed_passes() {
+  assert_http_success 200
+}
+
+function test_composed_fails() {
+  assert_http_success 500
+}
+
+function test_composed_in_a_loop_counts_every_call() {
+  local code
+  for code in 200 201 204; do
+    assert_http_success "$code"
+  done
+}
+
+function test_a_plain_assertion_after_a_composed_one_still_counts() {
+  assert_http_success 200
+  assert_same "a" "a"
+}
diff --git a/tests/unit/assert_once_test.sh b/tests/unit/assert_once_test.sh
new file mode 100644
index 00000000..74224b2a
--- /dev/null
+++ b/tests/unit/assert_once_test.sh
@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+
+function assert_http_success() {
+  bashunit::assert_once "a 2xx status" "$1"
+
+  assert_greater_or_equal_than "200" "$1"
+  assert_less_than "300" "$1"
+}
+
+function test_assert_once_counts_a_passing_composed_assertion_once() {
+  local counters
+  counters="$(
+    _BASHUNIT_ASSERTIONS_PASSED=0
+    _BASHUNIT_ASSERTIONS_FAILED=0
+    assert_http_success 200
+    bashunit::assert::once_flush
+    echo "$_BASHUNIT_ASSERTIONS_PASSED:$_BASHUNIT_ASSERTIONS_FAILED"
+  )"
+
+  assert_same "1:0" "$counters"
+}
+
+function test_assert_once_counts_a_failing_composed_assertion_once() {
+  local counters
+  counters="$(
+    # shellcheck disable=SC2317,SC2329
+    bashunit::console_results::print_line() { :; }
+    _BASHUNIT_ASSERTIONS_PASSED=0
+    _BASHUNIT_ASSERTIONS_FAILED=0
+    _BASHUNIT_ASSERTION_FAILED_IN_TEST=0
+    assert_http_success 500
+    bashunit::assert::once_flush
+    echo "$_BASHUNIT_ASSERTIONS_PASSED:$_BASHUNIT_ASSERTIONS_FAILED"
+  )"
+
+  assert_same "0:1" "$counters"
+}
+
+function test_assert_once_counts_every_call_when_looped() {
+  # Re-entering the declaring frame flushes the previous call, so calls from
+  # the same source line are not merged.
+  local counters
+  counters="$(
+    _BASHUNIT_ASSERTIONS_PASSED=0
+    _BASHUNIT_ASSERTIONS_FAILED=0
+    local code
+    for code in 200 201 204; do
+      assert_http_success "$code"
+    done
+    bashunit::assert::once_flush
+    echo "$_BASHUNIT_ASSERTIONS_PASSED:$_BASHUNIT_ASSERTIONS_FAILED"
+  )"
+
+  assert_same "3:0" "$counters"
+}
+
+function test_assert_once_stops_absorbing_once_the_declaring_frame_returns() {
+  local counters
+  counters="$(
+    _BASHUNIT_ASSERTIONS_PASSED=0
+    _BASHUNIT_ASSERTIONS_FAILED=0
+    assert_http_success 200
+    assert_same "a" "a"
+    bashunit::assert::once_flush
+    echo "$_BASHUNIT_ASSERTIONS_PASSED:$_BASHUNIT_ASSERTIONS_FAILED"
+  )"
+
+  assert_same "2:0" "$counters"
+}
+
+function test_assert_once_reports_the_custom_label_not_the_inner_message() {
+  assert_assertion_fails_with "a 2xx status" assert_http_success 500
+
+  assert_not_contains "to be less than" "$_BASHUNIT_ASSERT_INNER_OUTPUT_OUT"
+}
+
+function test_assert_once_does_not_leak_into_assert_assertion_helpers() {
+  # The isolation capture must neutralise an active marker, otherwise a custom
+  # assertion under test would swallow the verdict the capture reads back.
+  assert_assertion_passes assert_http_success 200
+  assert_assertion_fails assert_http_success 500
+}
+
+function test_assert_once_leaves_the_stop_on_failure_guard_for_the_flush() {
+  local guard
+  guard="$(
+    # shellcheck disable=SC2317,SC2329
+    bashunit::console_results::print_line() { :; }
+    _BASHUNIT_ASSERTION_FAILED_IN_TEST=0
+    assert_http_success 500
+    # Absorbed inner failures must not arm the guard before the flush decides.
+    local during=$_BASHUNIT_ASSERTION_FAILED_IN_TEST
+    bashunit::assert::once_flush
+    echo "$during:$_BASHUNIT_ASSERTION_FAILED_IN_TEST"
+  )"
+
+  assert_same "0:1" "$guard"
+}