feat(tests): add error handling for unexpected function calls

Add tests for `__refute_stream_line`, `__assert_stream`, and 
`__assert_line` to ensure they produce appropriate error messages 
when called directly. Update the implementations to handle 
unexpected calls by providing clear guidance on correct usage. 
This improves user experience and debugging by preventing silent 
failures and clarifying intended function usage.

Author: mh182

src/assert_line.bash

@@ -178,8 +178,12 @@ __assert_line() {
     local -ar stream_lines=("${stderr_lines[@]}")
     local -r stream_type=stderr
   else
-    # Coding error: unknown caller
-    :
+    # Unknown caller
+    echo "Unexpected call to \`${FUNCNAME[0]}\`
+Did you mean to call \`assert_line\` or \`assert_stderr_line\`?" \
+    | batslib_decorate "ERROR: ${FUNCNAME[0]}" \
+    | fail
+    return $?
   fi
 
   # Handle options.

src/assert_output.bash

@@ -170,8 +170,12 @@ __assert_stream() {
   elif [[ ${stream_type} == "stderr" ]]; then
     : "${stderr?}"
   else
-    # Not reachable: should be either output or stderr
-    :
+    # Unknown caller
+    echo "Unexpected call to \`${FUNCNAME[0]}\`
+Did you mean to call \`assert_output\` or \`assert_stderr\`?" |
+      batslib_decorate "ERROR: ${FUNCNAME[0]}" |
+      fail
+    return $?
   fi
   local -r stream="${!stream_type}"
 

src/refute_line.bash

@@ -175,8 +175,12 @@ __refute_stream_line() {
     local -ar stream_lines=("${stderr_lines[@]}")
     local -r stream_type=stderr
   else
-    # Coding error: unknown caller
-    :
+    # Unknown caller
+    echo "Unexpected call to \`${FUNCNAME[0]}\`
+Did you mean to call \`refute_line\` or \`refute_stderr_line\`?" |
+      batslib_decorate "ERROR: ${FUNCNAME[0]}" |
+      fail
+    return $?
   fi
 
   # Handle options.

test/assert_line.bats

@@ -349,3 +349,14 @@ ERR_MSG
   run assert_line -- '-p'
   assert_test_pass
 }
+
+@test "__assert_line(): call to __assert_line shows error" {
+  run __assert_line
+  assert_test_fail <<'ERR_MSG'
+
+-- ERROR: __assert_line --
+Unexpected call to `__assert_line`
+Did you mean to call `assert_line` or `assert_stderr_line`?
+--
+ERR_MSG
+}

test/assert_output.bats

@@ -283,3 +283,14 @@ ERR_MSG
   run assert_output -- '-p'
   assert_test_pass
 }
+
+@test "__assert_stream(): call to __assert_stream shows error" {
+  run __assert_stream
+  assert_test_fail <<'ERR_MSG'
+
+-- ERROR: __assert_stream --
+Unexpected call to `__assert_stream`
+Did you mean to call `assert_output` or `assert_stderr`?
+--
+ERR_MSG
+}

test/refute_line.bats

@@ -342,3 +342,14 @@ ERR_MSG
   run refute_line -- '-p'
   assert_test_pass
 }
+
+@test "__refute_stream_line(): call to __refute_stream_line shows error" {
+  run __refute_stream_line
+  assert_test_fail <<'ERR_MSG'
+
+-- ERROR: __refute_stream_line --
+Unexpected call to `__refute_stream_line`
+Did you mean to call `refute_line` or `refute_stderr_line`?
+--
+ERR_MSG
+}