bats-core · martin-schulze-vireso · Oct 22, 2022 · Oct 21, 2022 · Oct 21, 2022 · Oct 22, 2022
@@ -14,6 +14,12 @@ The format is based on [Keep a Changelog][kac] and this project adheres to
 
 * added installation instructions for Debian, Fedora, Gentoo, and OpenSUSE (#659)
 
+### Fixed
+
+#### Documentation
+
+* improved clarity of section about output in free code (#671)
+
 ## [1.8.2] - 2022-10-19
 
 ### Fixed

@@ -414,13 +414,12 @@ is not yet upgraded.
 
 ## Code outside of test cases
 
-You can include code in your test file outside of `@test` functions.  For
-example, this may be useful if you want to check for dependencies and fail
-immediately if they're not present. However, any output that you print in code
-outside of `@test`, `setup` or `teardown` functions must be redirected to
-`stderr` (`>&2`). Otherwise, the output may cause Bats to fail by polluting the
-TAP stream on `stdout`.
+In general you should avoid code outside tests, because it will be evaluated many times.
+However, there are situations in which this might be useful, e.g. when you want to check for dependencies and fail
+immediately if they're not present. 
 
+However, you should avoid printing outside of `@test`, `setup*` or `teardown*` functions.
+Have a look at section [printing to the terminal](#printing-to-the-terminal) for more details.
 ## File descriptor 3 (read this if Bats hangs)
 
 Bats makes a separation between output from the code under test and output that
@@ -467,20 +466,22 @@ your custom text. Here are some detailed guidelines to refer to:
     output. Otherwise, depending on the 3rd-party tools you use to analyze the
     TAP stream, you can encounter unexpected behavior or errors.
 
-- Printing **from within the `setup` or `teardown` functions**: The same hold
+- Printing **from within the `setup*` or `teardown*` functions**: The same hold
   true as for printing with test functions.
 
-- Printing **outside test or `setup`/`teardown` functions**:
-  - Regardless of where text is redirected to (stdout, stderr or file descriptor
-    3) text is immediately visible in the terminal.
+- Printing **outside test or `setup*`/`teardown*` functions**:
+  - You should avoid printing in free code: Due to the multiple executions
+    contexts (`setup_file`, multiple `@test`s)  of test files, output
+    will be printed more than once.
 
-  - Text printed in such a way, will disable pretty formatting. Also, it will
+  - Regardless of where text is redirected to
+    (stdout, stderr or file descriptor 3) text is immediately visible in the terminal, as it is not piped into the formatter.
+
+  - Text printed to stdout, may interfere with formatters as it can
     make output non-compliant with the TAP spec. The reason for this is that
-    each test file is evaluated n+1 times (as mentioned
-    [earlier](#writing-tests)). The first run will cause such output to be
-    produced before the [_plan line_][tap-plan] is printed, contrary to the spec
-    that requires the _plan line_ to be either the first or the last line of the
-    output.
+    such output will be produced before the [_plan line_][tap-plan] is printed,
+    contrary to the spec that requires the _plan line_ to be either the first or
+    the last line of the output.
 
   - Due to internal pipes/redirects, output to stderr is always printed first.
 

@@ -92,7 +92,7 @@ bats_run_setup_file() {
   local status=0
   # get the setup_file/teardown_file functions for this file (if it has them)
   # shellcheck disable=SC1090
-  source "$BATS_TEST_SOURCE" >>"$BATS_OUT" 2>&1
+  source "$BATS_TEST_SOURCE"
 
   BATS_SOURCE_FILE_COMPLETED=1
 

@@ -0,0 +1,7 @@
+echo stdout
+echo stderr >&2
+echo fd3 >&3
+
+@test fail {
+ true
+}