Add debugging output section to TESTS.md and adjust formatting (#768)

* Add debugging output section to TESTS.md and adjust formatting
* Add debugging guidance to README and TESTS.md; create DEBUGGING_LOCALLY.md
* Update debugging references in documentation for clarity and consistency
* Improve documentation for debugging: standardize casing and clarify file descriptor reference

Author: jooexploit

README.md

@@ -4,6 +4,8 @@
 
 Exercism Exercises in Bash
 
+If you are solving exercises locally and need help with Bats debug output, see [Debugging with `bats`](https://exercism.org/docs/tracks/bash/debugging).
+
 ## Contributing Guide
 
 Please see the [contributing guide](https://github.com/exercism/bash/blob/master/CONTRIBUTING.md) for information.

docs/DEBUGGING_LOCALLY.md

@@ -0,0 +1,27 @@
+# Debugging Locally
+
+When you run Bash track tests with [Bats](https://github.com/bats-core/bats-core), Bats captures both STDOUT and STDERR for output assertions.
+
+```exercism/caution
+This works locally with `bats`, but **not** in the Exercism online editor.
+```
+
+If you want to print debug output without affecting the test result, write it to file descriptor (fd) 3.
+
+```bash
+echo 'debug message' >&3
+```
+
+Bats shows output written to fd 3 during the test run, but it does not include that output in assertions such as `assert_output`.
+
+Example run:
+
+```none
+$ bats hello_world.bats
+hello_world.bats
+ ✓ Say Hi!
+debug message
+1 test, 0 failures
+```
+
+This is useful when you are running the tests locally.

docs/TESTS.md

@@ -39,6 +39,8 @@ cd /path/to/your/exercise_workspace/bash/whatever
 bats whatever.bats
 ```
 
+If you want to print debug output while running the tests locally, see [Debugging Locally](/docs/tracks/bash/debugging).
+
 ## Installing `bats-core`
 
 You should be able to install it from your favorite package manager:
@@ -56,8 +58,8 @@ $ brew install bats-core
 🍺  /usr/local/Cellar/bats-core/1.1.0: 13 files, 55KB, built in 4 seconds
 ```
 
-* The legacy `bats` package also exists in the homebrew ecosystem.
-    **_Do not install that by mistake_**: <u>install `bats-core`</u>.
+- The legacy `bats` package also exists in the homebrew ecosystem.
+  **_Do not install that by mistake_**: <u>install `bats-core`</u>.
 
 ### For Linux
 
@@ -124,7 +126,7 @@ annotations prepending other tests.
 
 ### Overriding skips
 
-To run all tests, including the ones with `skip` annotations, you can set an environment variable `BATS_RUN_SKIPPED` to the value `true`. 
+To run all tests, including the ones with `skip` annotations, you can set an environment variable `BATS_RUN_SKIPPED` to the value `true`.
 One way to set this just for the duration of running bats is:
 
 ```bash
@@ -153,7 +155,6 @@ Ownership was handed over in 2017: [sstephenson/bats#150 (comment)][bats-fork].
 
 If you have the original sstephenson/bats installed (check with `bats -v` reporting a version number less than 1.0), then you should switch to bats-core; otherwise you may find yourself [experiencing unexplained test failures][legacy-failures].
 
-
 [exercism-cli]: https://exercism.org/docs/using/solving-exercises/working-locally
 [bats]: https://github.com/bats-core/bats-core
 [bats-assert]: https://github.com/bats-core/bats-assert

docs/config.json

@@ -21,6 +21,13 @@
       "title": "Testing on the Bash track",
       "blurb": "Learn how to test your Bash exercises on Exercism"
     },
+    {
+      "uuid": "14a9f11d-ada7-4f5f-a9f5-2094b3e2e659",
+      "slug": "debugging",
+      "path": "docs/DEBUGGING_LOCALLY.md",
+      "title": "Debugging with `bats`",
+      "blurb": "Debugging your Bash code while testing with bats."
+    },
     {
       "uuid": "c74e1d25-18f1-4212-a10c-05303a962b1c",
       "slug": "resources",

exercises/shared/.docs/tests.md

@@ -7,10 +7,13 @@ Run the tests using the `bats` program.
 bats hello_world.bats
 ```
 
+If you need to print debug output while running tests locally, see [Debugging Locally][debugging].
+
 `bats` will need to be installed.
 See the [Testing on the Bash track][tests] page for instructions to install `bats` for your system.
 
 [tests]: https://exercism.org/docs/tracks/bash/tests
+[debugging]: https://exercism.org/docs/tracks/bash/debugging
 
 ## Help for assert functions
 
@@ -19,42 +22,6 @@ Help for the various `assert*` functions can be found there.
 
 [bats-assert]: https://github.com/bats-core/bats-assert
 
-## Debugging output
-
-```exercism/caution
-This works locally with `bats`, but **not** in the Exercism online editor.
-```
-
-When running tests, `bats` captures both stdout and stderr for comparison with the expected output.
-If you print debug messages to stdout (`echo`) or stderr (`>&2`), they will be included in the captured output and may cause the test to fail.
-
-To print debug information without affecting the test results, `bats` provides file descriptor **3** for this purpose.
-Anything redirected to `>&3` will be shown during the test run but will not be included in the captured output used for assertions.
-
-Example:
-
-```bash
-#!/usr/bin/env bash
-
-# This debug message will not interfere with test output comparison
-echo "debug message" >&3
-
-# Normal program output (this is what your tests will see and compare)
-echo "Hello, World!"
-```
-
-Example run:
-
-```none
-$ bats hello_world.bats
-hello_world.bats
- ✓ Say Hi!
-debug message
-1 test, 0 failures
-```
-
-This allows you to see helpful debug output without affecting the tests.
-
 ## Skipped tests
 
 Solving an exercise means making all its tests pass.