feat: add assert_stderr_line

Add a new assert_stderr_line function for checking expected lines
in the stderr output. This improves the clarity and functionality
of the assertion process.

Author: mh182

README.md

@@ -40,6 +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.
 
 These commands are described in more detail below.
 
@@ -897,6 +898,115 @@ Similar to `refute_output`, this function verifies that a command or function do
 The stderr matching can be literal (the default), partial or by regular expression.
 The unexpected stderr can be specified either by positional argument or read from STDIN by passing the `-`/`--stdin` flag.
 
+### `assert_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 `assert_stderr_line` to always fail.
+
+Similarly to `assert_stderr`, this function verifies that a command or function produces the expected stderr.
+It checks that the expected line appears in the stderr (default) or at a specific line number.
+Matching can be literal (default), partial or regular expression.
+This function is the logical complement of `refute_stderr_line`.
+
+#### Looking for a line in the stderr
+
+By default, the entire stderr is searched for the expected line.
+The assertion fails if the expected line is not found in `${stderr_lines[@]}`.
+
+  ```bash
+  echo_err() {
+    echo "$@" >&2
+  }
+
+  @test 'assert_stderr_line() looking for line' {
+    run --separate-stderr echo_err $'have-0\nhave-1\nhave-2'
+    assert_stderr_line 'want'
+  }
+  ```
+
+On failure, the expected line and the stderr are displayed.
+
+  ```
+  -- stderr does not contain line --
+  line : want
+  stderr (3 lines):
+    have-0
+    have-1
+  have-2
+  --
+  ```
+
+#### Matching a specific line
+
+When the `--index <idx>` option is used (`-n <idx>` for short), the expected line is matched only against the line identified by the given index.
+The assertion fails if the expected line does not equal `${stderr_lines[<idx>]}`.
+
+  ```bash
+  @test 'assert_stderr_line() specific line' {
+    run --separate-stderr echo_err $'have-0\nhave-1\nhave-2'
+    assert_stderr_line --index 1 'want-1'
+  }
+  ```
+
+On failure, the index and the compared stderr_lines are displayed.
+
+  ```
+  -- line differs --
+  index    : 1
+  expected : want-1
+  actual   : have-1
+  --
+  ```
+
+#### Partial matching
+
+Partial matching can be enabled with the `--partial` option (`-p` for short).
+When used, a match fails if the expected *substring* is not found in the matched line.
+
+  ```bash
+  @test 'assert_stderr_line() partial matching' {
+    run --separate-stderr echo_err $'have 1\nhave 2\nhave 3'
+    assert_stderr_line --partial 'want'
+  }
+  ```
+
+On failure, the same details are displayed as for literal matching, except that the substring replaces the expected line.
+
+  ```
+  -- no stderr line contains substring --
+  substring : want
+  stderr (3 lines):
+    have 1
+    have 2
+    have 3
+  --
+  ```
+
+#### Regular expression matching
+
+Regular expression matching can be enabled with the `--regexp` option (`-e` for short).
+When used, a match fails if the *extended regular expression* does not match the line being tested.
+
+*Note: As expected, the anchors `^` and `$` bind to the beginning and the end (respectively) of the matched line.*
+
+  ```bash
+  @test 'assert_stderr_line() regular expression matching' {
+    run --separate-stderr echo_err $'have-0\nhave-1\nhave-2'
+    assert_stderr_line --index 1 --regexp '^want-[0-9]$'
+  }
+  ```
+
+On failure, the same details are displayed as for literal matching, except that the regular expression replaces the expected line.
+
+  ```
+  -- regular expression does not match line --
+  index  : 1
+  regexp : ^want-[0-9]$
+  line   : have-1
+  --
+  ```
+
 <!-- REFERENCES -->
 
 [bats]: https://github.com/bats-core/bats-core

src/assert_line.bash

@@ -128,18 +128,65 @@
 #   ```
 # FIXME(ztombol): Display `${lines[@]}' instead of `$output'!
 assert_line() {
+  __assert_line "$@"
+}
+
+# assert_stderr_line
+# ===========
+#
+# Summary: Fail if the expected line is not found in the stderr (default) or at a specific line number.
+#
+# Usage: assert_stderr_line [-n index] [-p | -e] [--] <expected>
+#
+# Options:
+#   -n, --index <idx> Match the <idx>th line
+#   -p, --partial     Match if `expected` is a substring of `$stderr` or line <idx>
+#   -e, --regexp      Treat `expected` as an extended regular expression
+#   <expected>        The expected line string, substring, or regular expression
+#
+# IO:
+#   STDERR - details, on failure
+#            error message, on error
+# Globals:
+#   stderr
+#   stderr_lines
+# Returns:
+#   0 - if matching line found
+#   1 - otherwise
+#
+# Similarly to `assert_stderr`, this function verifies that a command or function produces the expected stderr.
+# (It is the logical complement of `refute_stderr_line`.)
+# It checks that the expected line appears in the stderr (default) or at a specific line number.
+# Matching can be literal (default), partial or regular expression.
+#
+assert_stderr_line() {
+  __assert_line "$@"
+}
+
+__assert_line() {
+  local -r caller=${FUNCNAME[1]}
   local -i is_match_line=0
   local -i is_mode_partial=0
   local -i is_mode_regexp=0
-  : "${lines?}"
+
+  if [[ "${caller}" == "assert_line" ]]; then
+    local -ar stream_lines=("${lines[@]}")
+    local -r stream_type=output
+  elif [[ "${caller}" == "assert_stderr_line" ]]; then
+    local -ar stream_lines=("${stderr_lines[@]}")
+    local -r stream_type=stderr
+  else
+    # Coding error: unknown caller
+    :
+  fi
 
   # Handle options.
   while (( $# > 0 )); do
     case "$1" in
     -n|--index)
       if (( $# < 2 )) || ! [[ $2 =~ ^-?([0-9]|[1-9][0-9]+)$ ]]; then
         echo "\`--index' requires an integer argument: \`$2'" \
-        | batslib_decorate 'ERROR: assert_line' \
+        | batslib_decorate "ERROR: ${caller}" \
         | fail
         return $?
       fi
@@ -156,7 +203,7 @@ assert_line() {
 
   if (( is_mode_partial )) && (( is_mode_regexp )); then
     echo "\`--partial' and \`--regexp' are mutually exclusive" \
-    | batslib_decorate 'ERROR: assert_line' \
+    | batslib_decorate "ERROR: ${caller}" \
     | fail
     return $?
   fi
@@ -166,7 +213,7 @@ assert_line() {
 
   if (( is_mode_regexp == 1 )) && [[ '' =~ $expected ]] || (( $? == 2 )); then
     echo "Invalid extended regular expression: \`$expected'" \
-    | batslib_decorate 'ERROR: assert_line' \
+    | batslib_decorate "ERROR: ${caller}" \
     | fail
     return $?
   fi
@@ -175,73 +222,73 @@ assert_line() {
   if (( is_match_line )); then
     # Specific line.
     if (( is_mode_regexp )); then
-      if ! [[ ${lines[$idx]} =~ $expected ]]; then
+      if ! [[ ${stream_lines[$idx]} =~ $expected ]]; then
         batslib_print_kv_single 6 \
         'index' "$idx" \
         'regexp' "$expected" \
-        'line'  "${lines[$idx]}" \
+        'line'  "${stream_lines[$idx]}" \
         | batslib_decorate 'regular expression does not match line' \
         | fail
       fi
     elif (( is_mode_partial )); then
-      if [[ ${lines[$idx]} != *"$expected"* ]]; then
+      if [[ ${stream_lines[$idx]} != *"$expected"* ]]; then
         batslib_print_kv_single 9 \
         'index'     "$idx" \
         'substring' "$expected" \
-        'line'      "${lines[$idx]}" \
+        'line'      "${stream_lines[$idx]}" \
         | batslib_decorate 'line does not contain substring' \
         | fail
       fi
     else
-      if [[ ${lines[$idx]} != "$expected" ]]; then
+      if [[ ${stream_lines[$idx]} != "$expected" ]]; then
         batslib_print_kv_single 8 \
         'index'    "$idx" \
         'expected' "$expected" \
-        'actual'   "${lines[$idx]}" \
+        'actual'   "${stream_lines[$idx]}" \
         | batslib_decorate 'line differs' \
         | fail
       fi
     fi
   else
-    # Contained in output.
+    # Contained in output/error stream.
     if (( is_mode_regexp )); then
       local -i idx
-      for (( idx = 0; idx < ${#lines[@]}; ++idx )); do
-        [[ ${lines[$idx]} =~ $expected ]] && return 0
+      for (( idx = 0; idx < ${#stream_lines[@]}; ++idx )); do
+        [[ ${stream_lines[$idx]} =~ $expected ]] && return 0
       done
       { local -ar single=( 'regexp' "$expected" )
-        local -ar may_be_multi=( 'output' "$output" )
+        local -ar may_be_multi=( "${stream_type}" "${!stream_type}" )
         local -ir width="$( batslib_get_max_single_line_key_width "${single[@]}" "${may_be_multi[@]}" )"
         batslib_print_kv_single "$width" "${single[@]}"
         batslib_print_kv_single_or_multi "$width" "${may_be_multi[@]}"
       } \
-      | batslib_decorate 'no output line matches regular expression' \
+      | batslib_decorate "no ${stream_type} line matches regular expression" \
       | fail
     elif (( is_mode_partial )); then
       local -i idx
-      for (( idx = 0; idx < ${#lines[@]}; ++idx )); do
-        [[ ${lines[$idx]} == *"$expected"* ]] && return 0
+      for (( idx = 0; idx < ${#stream_lines[@]}; ++idx )); do
+        [[ ${stream_lines[$idx]} == *"$expected"* ]] && return 0
       done
       { local -ar single=( 'substring' "$expected" )
-        local -ar may_be_multi=( 'output' "$output" )
+        local -ar may_be_multi=( "${stream_type}" "${!stream_type}" )
         local -ir width="$( batslib_get_max_single_line_key_width "${single[@]}" "${may_be_multi[@]}" )"
         batslib_print_kv_single "$width" "${single[@]}"
         batslib_print_kv_single_or_multi "$width" "${may_be_multi[@]}"
       } \
-      | batslib_decorate 'no output line contains substring' \
+      | batslib_decorate "no ${stream_type} line contains substring" \
       | fail
     else
       local -i idx
-      for (( idx = 0; idx < ${#lines[@]}; ++idx )); do
-        [[ ${lines[$idx]} == "$expected" ]] && return 0
+      for (( idx = 0; idx < ${#stream_lines[@]}; ++idx )); do
+        [[ ${stream_lines[$idx]} == "$expected" ]] && return 0
       done
       { local -ar single=( 'line' "$expected" )
-        local -ar may_be_multi=( 'output' "$output" )
+        local -ar may_be_multi=( "${stream_type}" "${!stream_type}" )
         local -ir width="$( batslib_get_max_single_line_key_width "${single[@]}" "${may_be_multi[@]}" )"
         batslib_print_kv_single "$width" "${single[@]}"
         batslib_print_kv_single_or_multi "$width" "${may_be_multi[@]}"
       } \
-      | batslib_decorate 'output does not contain line' \
+      | batslib_decorate "${stream_type} does not contain line" \
       | fail
     fi
   fi