Replace run --output <mode> by --separate-stderr

Reading only stderr/stdout can be achieved by the separation as well.
Performance did not differ much. We can still revive these options later on
but taking them back won't be possible.

docs/CHANGELOG.md

@@ -25,8 +25,8 @@ The format is based on [Keep a Changelog][kac] and this project adheres to
   folder name to allow for multilib install, e.g. into lib64 (#452)
 * add `run` flag `--keep-empty-lines` to retain empty lines in `${lines[@]}` (#224,
   a894fbfa)
-* add `run` flag `--output merged|separate|stderr|stdout` (default: `merged`) to
-  select how `$output` and `$lines` are filled (#47, 5c9b173d)
+* add `run` flag `--separate-stderr` which also fills `$stderr` and
+  `$stderr_lines` (#47, 5c9b173d, #507)
 
 ### Fixed
 

docs/source/writing-tests.md

@@ -70,18 +70,11 @@ __Note:__ The `run` helper executes its argument(s) in a subshell, so if
 writing tests against environmental side-effects like a variable's value
 being changed, these changes will not persist after `run` completes.
 
-By default `run` leaves out empty lines in `${lines[@]}`. Use 
+By default `run` leaves out empty lines in `${lines[@]}`. Use
 `run --keep-empty-lines` to retain them.
 
-Additionally, you can use `run --output <mode>` to control what goes into
-`$output` and `$lines`. The available values for `<mode>` are:
-
-- `merged`: the default when `--output` is not specified, interleaves stdout and
-  stderr
-- `separate`: splits stderr off to `$stderr` and `${stderr_lines[@]}`, stdout is
-  still available as `$output` and `${lines[@]}`
-- `stderr`: discards stdout and fills '$stderr` and `${stderr_lines[@]}`
-- `stdout`: discards stdout and fills `$output` and `${lines[@]}`
+Additionally, you can use `--separate-stderr` to split stdout and stderr
+into `$output`/`$stderr` and `${lines[@]}`/`${stderr_lines[@]}`.
 
 All additional parameters to run should come before the command.
 If you want to run a command that starts with `-`, prefix it with `--` to

lib/bats-core/test_functions.bash

@@ -29,16 +29,6 @@ load() {
   source "${file}"
 }
 
-bats_suppress_stderr() {
-  "$@" 2>/dev/null
-}
-
-bats_suppress_stdout() {
-  # throw away stdout and redirect stderr into stdout
-  # shellcheck disable=SC2069
-  "$@" 2>&1 >/dev/null 
-}
-
 bats_redirect_stderr_into_file() {
   "$@" 2>>"$bats_run_separate_stderr_file" # use >> to see collisions' content
 }
@@ -63,7 +53,7 @@ bats_separate_lines() { # <output-array> <input-var>
   fi
 }
 
-run() { # [!|-N] [--keep-empty-lines] [--output merged|separate|stderr|stdout] [--] <command to run...>
+run() { # [!|-N] [--keep-empty-lines] [--separate-stderr] [--] <command to run...>
   trap bats_interrupt_trap_in_run INT
   local expected_rc=
   local keep_empty_lines=
@@ -87,10 +77,8 @@ run() { # [!|-N] [--keep-empty-lines] [--output merged|separate|stderr|stdout] [
       --keep-empty-lines)
         keep_empty_lines=1
       ;;
-      --output)
-        output_case="$2"
-        shift 2 # consume the value too!
-        continue
+      --separate-stderr)
+        output_case="separate"
       ;;
       --)
         shift # eat the -- before breaking away
@@ -111,16 +99,6 @@ run() { # [!|-N] [--keep-empty-lines] [--output merged|separate|stderr|stdout] [
       bats_run_separate_stderr_file="$(mktemp "${BATS_TEST_TMPDIR}/separate-stderr-XXXXXX")"
       pre_command=bats_redirect_stderr_into_file
     ;;
-    stderr) # suppresses stdout and fills $stderr/$stderr_lines
-      pre_command=bats_suppress_stdout
-    ;;
-    stdout) # suppresses stderr and fills $output/$lines
-      pre_command=bats_suppress_stderr
-    ;;
-    *)
-      printf "ERROR: Unknown --output value %s" "$output_case"
-      return 1
-    ;;
   esac
 
   local origFlags="$-"

man/bats.7.ronn

@@ -35,8 +35,10 @@ Usage: run [OPTIONS] [--] <command...>
 Options:
        !        check for non zero exit code
        -<N>     check that exit code is <N>
+       --separate-stderr
+                split stderr and stdout
        --keep-empty-lines
-                retain emtpy lines in `${lines[@]}`
+                retain emtpy lines in `${lines[@]}`/`${stderr_lines[@]}`
 
 Many Bats tests need to run a command and then make assertions about
 its exit status and output. Bats includes a `run` helper that invokes
@@ -82,13 +84,8 @@ the first line:
 
 By default `run` leaves out empty lines in `${lines[@]}`. Use `run --keep-empty-lines` to retain them.
 
-Additionally, you can use `run --output <mode>` to control what goes into `$output` and `$lines`.
-The available values for `<mode>` are:
-
-- `merged`: the default when `--output` is not specified, interleaves stdout and stderr
-- `separate`: splits stderr off to `$stderr` and `${stderr_lines[@]}`, stdout is still available as `$output` and `${lines[@]}`
-- `stderr`: discards stdout and fills '$stderr` and `${stderr_lines[@]}`
-- `stdout`: discards stdout and fills `$output` and `${lines[@]}`
+Additionally, you can use `--separate-stderr` to split stdout and stderr
+into `$output`/`$stderr` and `${lines[@]}`/`${stderr_lines[@]}`.
 
 All additional parameters to run should come before the command.
 If you want to run a command that starts with `-`, prefix it with `--` to

test/run.bats

@@ -48,44 +48,8 @@ print-stderr-stdout() {
     printf stderr >&2
 }
 
-@test "run --output stdout does not print stderr" {   
-    run --output stdout -- print-stderr-stdout
-    # SC does not know about $stderr* yet
-    # shellcheck disable=SC2154
-    echo "output='$output' stderr='$stderr'"
-    [ "$output" = "stdout" ]
-    [ ${#lines[@]} -eq 1 ]
-
-    # SC does not know about $stderr* yet
-    # shellcheck disable=SC2154
-    [ "${stderr-notset}" = notset ]
-    # SC does not know about $stderr* yet
-    # shellcheck disable=SC2154
-    [ ${#stderr_lines[@]} -eq 0 ]
-}
-
-@test "run --output stderr does not print stdout" {
-    run --output stderr -- print-stderr-stdout
-    echo "output='$output' stderr='$stderr'"
-    [ "${output-notset}" = notset ]
-    [ ${#lines[@]} -eq 0 ]
-
-    [ "$stderr" = stderr ]
-    [ ${#stderr_lines[@]} -eq 1 ]
-}
-
-@test "--output works without -- separator" {
-    run --output stderr print-stderr-stdout
-    echo "output='$output' stderr='$stderr'"
-    [ "${output-notset}" = notset ]
-    [ ${#lines[@]} -eq 0 ]
-
-    [ "$stderr" = stderr ]
-    [ ${#stderr_lines[@]} -eq 1 ]
-}
-
-@test "run --output separate splits output" {
-    run --output separate -- print-stderr-stdout
+@test "run --separate-stderr splits output" {
+    run --separate-stderr -- print-stderr-stdout
     echo "output='$output' stderr='$stderr'"
     [ "$output" = stdout ]
     [ ${#lines[@]} -eq 1 ]