bats-core · martin-schulze-vireso · Mar 13, 2023 · Mar 4, 2023 · Mar 4, 2023 · Mar 4, 2023
@@ -15,6 +15,11 @@ The format is based on [Keep a Changelog][kac] and this project adheres to
 * add `${BATS_TEST_TAGS[@]}` for querying the tags during a test (#705)
 * print tags on failing tests (#705)
 * test for negative arguments to `--jobs` (#693)
+* add tests for `--formatter cat` (#710)
+
+### Documentation
+
+* clarify use cases of `--formatter cat` (#710)
 
 ### Fixed
 

@@ -194,6 +194,22 @@ your own fork of the repository and issuing pull requests to the original.
 
 - Continuous integration status: [![Tests](https://github.com/bats-core/bats-core/workflows/Tests/badge.svg)](https://github.com/bats-core/bats-core/actions?query=workflow%3ATests)
 
+To run all tests:
+```sh
+bin/bats test
+```
+
+To run a single test file:
+```sh
+bin/bats test/file.bats
+```
+
+When running from a teminal, Bats uses the *pretty* formatter by default.
+However, to debug Bats you might need to see the raw test output. 
+The **cat** formatter is intended as an internal debugging tool because
+it does not process test outputs.
+To use it, run Bats with the `--formatter cat` option.
+
 ## Coding conventions
 
 - [Formatting](#formatting)

@@ -0,0 +1,70 @@
+load 'test_helper'
+fixtures bats # reuse bats fixtures
+
+@test "passing test" {
+  reentrant_run bats --formatter cat "${FIXTURE_ROOT}/passing.bats"
+
+  [ "${lines[0]}" == '1..1' ]
+  [ "${lines[1]}" == "suite ${FIXTURE_ROOT}/passing.bats" ]
+  [ "${lines[2]}" == 'begin 1 a passing test' ]
+  [ "${lines[3]}" == 'ok 1 a passing test' ]
+  [ "${#lines[@]}" -eq 4 ]
+}
+
+@test "failing test" {
+  reentrant_run bats --formatter cat "${FIXTURE_ROOT}/failing.bats"
+
+  [ "${lines[0]}" == '1..1' ]
+  [ "${lines[1]}" == "suite ${FIXTURE_ROOT}/failing.bats" ]
+  [ "${lines[2]}" == 'begin 1 a failing test' ]
+  [ "${lines[3]}" == 'not ok 1 a failing test' ]
+  [ "${lines[4]}" == "# (in test file ${RELATIVE_FIXTURE_ROOT}/failing.bats, line 4)" ]
+  [ "${lines[5]}" == "#   \`eval \"( exit \${STATUS:-1} )\"' failed" ]
+  [ "${#lines[@]}" -eq 6 ]
+}
+
+@test "passing test with timing" {
+  reentrant_run bats --formatter cat --timing "${FIXTURE_ROOT}/passing.bats"
+
+  [ "${lines[0]}" == '1..1' ]
+  [ "${lines[1]}" == "suite ${FIXTURE_ROOT}/passing.bats" ]
+  [ "${lines[2]}" == 'begin 1 a passing test' ]
+  [ "${lines[3]::23}" == 'ok 1 a passing test in ' ]
+  [ "${lines[3]: -2}" == 'ms' ]
+  [ "${#lines[@]}" -eq 4 ]
+}
+
+@test "failing test with timing" {
+  reentrant_run bats --formatter cat --timing "${FIXTURE_ROOT}/failing.bats"
+
+  [ "${lines[0]}" == '1..1' ]
+  [ "${lines[1]}" == "suite ${FIXTURE_ROOT}/failing.bats" ]
+  [ "${lines[2]}" == 'begin 1 a failing test' ]
+  [ "${lines[3]::27}" == 'not ok 1 a failing test in ' ]
+  [ "${lines[3]: -2}" == 'ms' ]
+  [ "${lines[4]}" == "# (in test file ${RELATIVE_FIXTURE_ROOT}/failing.bats, line 4)" ]
+  [ "${lines[5]}" == "#   \`eval \"( exit \${STATUS:-1} )\"' failed" ]
+  [ "${#lines[@]}" -eq 6 ]
+}
+
+@test "Cat formatter prints the extended tap stream" {
+  cd "$BATS_ROOT/libexec/bats-core/"
+
+  local formatter="bats-format-cat"
+
+  reentrant_run bash -u "$formatter" <<EOF
+1..1
+suite "$FIXTURE_ROOT/failing.bats"
+# output from setup_file
+begin 1 test_a_failing_test
+# fd3 output from test
+not ok 1 a failing test
+# (in test file test/fixtures/bats/failing.bats, line 4)
+#   \`eval "( exit ${STATUS:-1} )"' failed
+begin 2 test_a_successful_test
+ok 2 a succesful test
+unknown line
+EOF
+
+  [[ "${#lines[@]}" -eq 11 ]]
+}