feat(doubles): add assert_have_been_called_nth_with assertion

    Adds dedicated assertion to verify arguments passed on the Nth
    invocation of a spy, with explicit API and index bounds checking.

Author: Chemaclass

.claude/settings.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "includeCoAuthoredBy": false
+}

src/test_doubles.sh

@@ -156,6 +156,49 @@ function assert_have_been_called_times() {
   bashunit::state::add_assertions_passed
 }
 
+function assert_have_been_called_nth_with() {
+  local nth=$1
+  local command=$2
+  shift 2
+  local expected="$*"
+
+  local variable
+  variable="$(bashunit::helper::normalize_variable_name "$command")"
+  local times_file_var="${variable}_times_file"
+  local file_var="${variable}_params_file"
+  local label
+  label="$(bashunit::helper::normalize_test_function_name "${FUNCNAME[1]}")"
+
+  local times=0
+  if [ -f "${!times_file_var-}" ]; then
+    times=$(cat "${!times_file_var}" 2>/dev/null || echo 0)
+  fi
+
+  if [ "$nth" -gt "$times" ]; then
+    bashunit::state::add_assertions_failed
+    bashunit::console_results::print_failed_test "${label}" \
+      "expected call" "at index ${nth} but" "only called ${times} times"
+    return
+  fi
+
+  local line=""
+  if [ -f "${!file_var-}" ]; then
+    line=$(sed -n "${nth}p" "${!file_var}" 2>/dev/null || true)
+  fi
+
+  local raw
+  IFS=$'\x1e' read -r raw _ <<<"$line" || true
+
+  if [ "$expected" != "$raw" ]; then
+    bashunit::state::add_assertions_failed
+    bashunit::console_results::print_failed_test "${label}" \
+      "$expected" "but got " "$raw"
+    return
+  fi
+
+  bashunit::state::add_assertions_passed
+}
+
 function assert_not_called() {
   local command=$1
   local label="${2:-$(bashunit::helper::normalize_test_function_name "${FUNCNAME[1]}")}"

tests/unit/test_doubles_test.sh

@@ -177,3 +177,40 @@ function test_spy_with_pipe_in_arguments() {
 
   assert_have_been_called_with grep '-E foo|bar'
 }
+
+function test_successful_spy_nth_called_with() {
+  bashunit::spy ps
+
+  ps first_a first_b
+  ps second
+  ps third
+
+  assert_have_been_called_nth_with 1 ps "first_a first_b"
+  assert_have_been_called_nth_with 2 ps "second"
+  assert_have_been_called_nth_with 3 ps "third"
+}
+
+function test_unsuccessful_spy_nth_called_with() {
+  bashunit::spy ps
+
+  ps first
+  ps second
+
+  assert_same \
+    "$(bashunit::console_results::print_failed_test \
+      "Unsuccessful spy nth called with" \
+      "wrong" "but got " "first")" \
+    "$(assert_have_been_called_nth_with 1 ps "wrong")"
+}
+
+function test_unsuccessful_spy_nth_called_with_invalid_index() {
+  bashunit::spy ps
+
+  ps first
+
+  assert_same \
+    "$(bashunit::console_results::print_failed_test \
+      "Unsuccessful spy nth called with invalid index" \
+      "expected call" "at index 5 but" "only called 1 times")" \
+    "$(assert_have_been_called_nth_with 5 ps "first")"
+}