Docs: Update printing from free code
diff --git a/docs/source/writing-tests.md b/docs/source/writing-tests.md index fdb685d..df8ff33 100644 --- a/docs/source/writing-tests.md +++ b/docs/source/writing-tests.md
@@ -414,13 +414,12 @@ ## 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 @@ 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.
diff --git a/test.bats b/test.bats new file mode 100644 index 0000000..c2077fa --- /dev/null +++ b/test.bats
@@ -0,0 +1,7 @@ +echo stdout +echo stderr >&2 +echo fd3 >&3 + +@test fail { + true +}