feat: add assert_stderr, refute_stderr, assert_stderr_line, refute_stderr_line

Refactor the `assert_output` function to improve clarity and
maintainability. Introduce a new helper function `__assert_stream`
to handle different stream types (output and stderr).

Introduce the `assert_stderr` function to validate that the
standard error output matches the expected value.

Refactor the `refute_output` function to improve stream handling by
introducing a new `__refute_stream` function. This change allows for
more flexible handling of both `output` and `stderr` streams. This
enhances the maintainability and usability of the code.

Introduce the `refute_stderr` function to allow verification that a command
or function does not produce unexpected stderr. This function complements
`assert_stderr` and supports matching via literal, partial, or regular
expression. Update documentation to reflect this addition and clarify
usage of `assert_stderr` with `--separate-stderr` for proper stderr
handling.

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.

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

@@ -39,6 +39,8 @@ This project provides the following functions:
  - [assert_output](#assert_output) / [refute_output](#refute_output) Assert output does (or does not) contain given content.
  - [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) / [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.
 
@@ -750,7 +752,7 @@ Fail if the value (first parameter) matches the pattern (second parameter).
 
 On failure, the value, the pattern and the match are displayed.
 
-```
+```bash
 @test 'refute_regex()' {
   refute_regex 'WhatsApp' 'What.'
 }
@@ -777,6 +779,245 @@ For description of the matching behavior, refer to the documentation of the
 > Thus, it's good practice to avoid using `BASH_REMATCH` in conjunction with `refute_regex()`.
 > The valuable information the array contains is the matching part of the value which is printed in the failing test log, as mentioned above._
 
+### `assert_stderr`
+
+> _**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` to always fail.
+
+Similarly to `assert_output`, this function verifies that a command or function produces the expected stderr.
+The stderr matching can be literal (the default), partial or by regular expression.
+The expected stderr can be specified either by positional argument or read from STDIN by passing the `-`/`--stdin` flag.
+
+#### Literal matching
+
+By default, literal matching is performed.
+The assertion fails if `$stderr` does not equal the expected stderr.
+
+  ```bash
+  echo_err() {
+    echo "$@" >&2
+  }
+
+  @test 'assert_stderr()' {
+    run --separate-stderr echo_err 'have'
+    assert_stderr 'want'
+  }
+
+  @test 'assert_stderr() with pipe' {
+    run --separate-stderr echo_err 'hello'
+    echo_err 'hello' | assert_stderr -
+  }
+
+  @test 'assert_stderr() with herestring' {
+    run --separate-stderr echo_err 'hello'
+    assert_stderr - <<< hello
+  }
+  ```
+
+On failure, the expected and actual stderr are displayed.
+
+  ```
+  -- stderr differs --
+  expected : want
+  actual   : have
+  --
+  ```
+
+#### Existence
+
+To assert that any stderr exists at all, omit the `expected` argument.
+
+  ```bash
+  @test 'assert_stderr()' {
+    run --separate-stderr echo_err 'have'
+    assert_stderr
+  }
+  ```
+
+On failure, an error message is displayed.
+
+  ```
+  -- no stderr --
+  expected non-empty stderr, but stderr was empty
+  --
+  ```
+
+#### Partial matching
+
+Partial matching can be enabled with the `--partial` option (`-p` for short).
+When used, the assertion fails if the expected _substring_ is not found in `$stderr`.
+
+  ```bash
+  @test 'assert_stderr() partial matching' {
+    run --separate-stderr echo_err 'ERROR: no such file or directory'
+    assert_stderr --partial 'SUCCESS'
+  }
+  ```
+
+On failure, the substring and the stderr are displayed.
+
+  ```
+  -- stderr does not contain substring --
+  substring : SUCCESS
+  stderr    : ERROR: no such file or directory
+  --
+  ```
+
+#### Regular expression matching
+
+Regular expression matching can be enabled with the `--regexp` option (`-e` for short).
+When used, the assertion fails if the *extended regular expression* does not match `$stderr`.
+
+*Note: The anchors `^` and `$` bind to the beginning and the end (respectively) of the entire stderr; not individual lines.*
+
+  ```bash
+  @test 'assert_stderr() regular expression matching' {
+    run --separate-stderr echo_err 'Foobar 0.1.0'
+    assert_stderr --regexp '^Foobar v[0-9]+\.[0-9]+\.[0-9]$'
+  }
+  ```
+
+On failure, the regular expression and the stderr are displayed.
+
+  ```
+  -- regular expression does not match stderr --
+  regexp : ^Foobar v[0-9]+\.[0-9]+\.[0-9]$
+  stderr : Foobar 0.1.0
+  --
+  ```
+
+### `refute_stderr`
+
+> _**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` to always pass.
+
+Similar to `refute_output`, this function verifies that a command or function does not produce the unexpected stderr.
+(It is the logical complement of `assert_stderr`.)
+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
+  --
+  ```
+
+### `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