feat: add refute_stderr_line

Refactor the `refute_line` function to handle both output and
stderr streams uniformly. Introduce a new helper function
`__refute_stream_line` to streamline the logic and reduce
code duplication.

Introduce the `refute_stderr_line` function to verify that an
unexpected line does not appear in the stderr output. Update
documentation to reflect usage and necessary conditions for correct
operation, including the requirement to use `--separate-stderr`
when running commands.

Author: mh182

README.md

@@ -40,7 +40,7 @@ This project provides the following functions:
  - [assert_line](#assert_line) / [refute_line](#refute_line) Assert a specific line of output does (or does not) contain given content.
  - [assert_regex](#assert_regex) / [refute_regex](#refute_regex) Assert a parameter does (or does not) match given pattern.
  - [assert_stderr](#assert_stderr) / [refute_stderr](#refute_stderr) Assert stderr does (or does not) contain given content.
- - [assert_stderr_line](#assert_stderr_line) Assert a specific line of stderr does contain given content.
+ - [assert_stderr_line](#assert_stderr_line) / [refute_stderr_line](#refute_stderr_line) Assert a specific line of stderr does (or does not) contain given content.
 
 These commands are described in more detail below.
 
@@ -1007,6 +1007,17 @@ On failure, the same details are displayed as for literal matching, except that
   --
   ```
 
+### `refute_stderr_line`
+
+> _**Note**:
+> `run` has to be called with `--separate-stderr` to separate stdout and stderr into `$output` and `$stderr`.
+> If not, `$stderr` will be empty, causing `refute_stderr_line` to always pass.
+
+Similarly to `refute_stderr`, this function helps to verify that a command or function produces the correct stderr.
+It checks that the unexpected line does not appear in the stderr (default) or in a specific line of it.
+Matching can be literal (default), partial or regular expression.
+This function is the logical complement of `assert_stderr_line`.
+
 <!-- REFERENCES -->
 
 [bats]: https://github.com/bats-core/bats-core

src/refute_line.bash

@@ -128,6 +128,38 @@ refute_line() {
   __refute_stream_line "$@"
 }
 
+# refute_stderr_line
+# ==================
+#
+# Summary: Fail if the unexpected line is found in the stderr (default) or at a specific line number.
+#
+# Usage: refute_stderr_line [-n index] [-p | -e] [--] <unexpected>
+#
+# Options:
+#   -n, --index <idx> Match the <idx>th line
+#   -p, --partial     Match if `unexpected` is a substring of `$stderr` or line <idx>
+#   -e, --regexp      Treat `unexpected` as an extended regular expression
+#   <unexpected>      The unexpected line string, substring, or regular expression.
+#
+# IO:
+#   STDERR - details, on failure
+#            error message, on error
+# Globals:
+#   stderr
+#   stderr_lines
+# Returns:
+#   0 - if match not found
+#   1 - otherwise
+#
+# Similarly to `refute_stderr`, this function verifies that a command or function does not produce the unexpected stderr.
+# (It is the logical complement of `assert_stderr_line`.)
+# It checks that the unexpected line does not appear in the stderr (default) or at a specific line number.
+# Matching can be literal (default), partial or regular expression.
+#
+refute_stderr_line() {
+  __refute_stream_line "$@"
+}
+
 __refute_stream_line() {
   local -r caller=${FUNCNAME[1]}
   local -i is_match_line=0