fix(doubles): a non-numeric spy count leaked a raw shell error

CHANGELOG.md

@@ -18,6 +18,7 @@
 - Internal: Split `src/runner.sh` and `src/coverage.sh` into focused modules with no behavior change; see [ADR-010](adrs/adr-010-src-module-directories.md) (#924, #925)
 
 ### Fixed
+- `assert_have_been_called_times` and `assert_have_been_called_nth_with` report a usage error when their numeric argument is not a number, instead of leaking `[: my_cmd: integer expression expected` from inside bashunit. The common cause is swapping the count and the spy, which the message now names (#984)
 - `assert_false` no longer passes when the command does not exist. Exit code 127 is non-zero, so a typo in the command name satisfied the assertion while testing nothing; 127 and 126 now fail both `assert_true` and `assert_false`, because they mean the command never ran
 - `assert_within_delta` accepts a leading `+` on any operand (#979)
 - Invalid `BASHUNIT_SHARD_INDEX` / `BASHUNIT_SHARD_TOTAL` values now fail with a clear error instead of reaching raw arithmetic or reporting no tests

src/assert/core.sh

@@ -22,6 +22,19 @@ function bashunit::assert::should_skip() {
 
 # Emits a machine-detectable assertion usage error. The runner strips the
 # prefix and reports the message through the existing Error channel.
+##
+# Emits a machine-detectable assertion usage error for an argument of the wrong
+# *shape*, as opposed to a missing one. Same prefix as usage_error, so the
+# runner strips it and reports through the existing Error channel.
+# Arguments: $1 - assertion name, $2 - the rest of the sentence
+##
+function bashunit::assert::usage_error_detail() {
+  local assertion=$1
+  local detail=$2
+
+  printf 'bashunit: assertion usage error: %s %s\n' "$assertion" "$detail" >&2
+}
+
 function bashunit::assert::usage_error() {
   local assertion=$1
   local required=$2

src/doubles/assertions.sh

@@ -164,6 +164,18 @@ function assert_have_been_called_with_any() {
 function assert_have_been_called_times() {
   local expected_count=$1
   local command=$2
+
+  # Guarded before the spy lookup so a swapped call is diagnosed as the ordering
+  # mistake it is, rather than as "the count you passed is not a registered
+  # spy". Without this the value reaches `[ "$times" -ne "$expected_count" ]`
+  # and bash prints "integer expression expected" from inside bashunit.
+  case "$expected_count" in
+  '' | *[!0-9]*)
+    bashunit::assert::usage_error_detail "${FUNCNAME[0]}" \
+      "expects a numeric count first (expected_count, command), got '$expected_count'"
+    return 2
+    ;;
+  esac
   bashunit::spy::times_to_slot "$command"
   local times=$_BASHUNIT_SPY_TIMES_OUT
   local label="${3:-}"
@@ -192,6 +204,16 @@ function assert_have_been_called_times() {
 
 function assert_have_been_called_nth_with() {
   local nth=$1
+
+  # Same guard as assert_have_been_called_times: $nth reaches an integer
+  # comparison below.
+  case "$nth" in
+  '' | *[!0-9]*)
+    bashunit::assert::usage_error_detail "${FUNCNAME[0]}" \
+      "expects a numeric call index first (nth, command, expected_args), got '$nth'"
+    return 2
+    ;;
+  esac
   local command=$2
   shift 2
   local expected="$*"

tests/acceptance/bashunit_spy_usage_test.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+function test_non_numeric_spy_count_is_a_usage_error() {
+  local fixture=tests/acceptance/fixtures/spy_usage/non_numeric.sh
+  local output exit_code=0
+
+  output=$(NO_COLOR=1 ./bashunit --no-parallel --skip-env-file "$fixture" 2>&1) || exit_code=$?
+
+  assert_same 1 "$exit_code"
+  assert_contains "✗ Error: Swapped count and spy" "$output"
+  assert_contains \
+    "assert_have_been_called_times expects a numeric count first (expected_count, command), got 'my_cmd'" \
+    "$output"
+  # The raw shell diagnostic must not reach the user.
+  assert_not_contains "integer expression expected" "$output"
+}

tests/acceptance/fixtures/spy_usage/non_numeric.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+
+function my_cmd() { echo x; }
+
+# The spy and the count swapped: assert_have_been_called_times takes the count
+# first. Without a guard this reaches `[ 1 -ne my_cmd ]` and leaks a raw
+# "integer expression expected" from inside bashunit.
+function test_swapped_count_and_spy() {
+  bashunit::spy my_cmd
+  my_cmd >/dev/null
+  assert_have_been_called_times my_cmd 1
+}