From 0788a12aeff4ba70d441f248522b196b7f02ca50 Mon Sep 17 00:00:00 2001
From: Glenn Jackman <glenn.jackman@gmail.com>
Date: Thu, 18 Sep 2025 17:38:07 -0400
Subject: [PATCH 1/2] Document how to print debug output without breaking bats
 testing

---
 exercises/shared/.docs/tests.md | 48 +++++++++++++++++++++++++++++++++
 1 file changed, 48 insertions(+)

diff --git a/exercises/shared/.docs/tests.md b/exercises/shared/.docs/tests.md
index 7d5cfae..9ef1995 100644
--- a/exercises/shared/.docs/tests.md
+++ b/exercises/shared/.docs/tests.md
@@ -28,6 +28,54 @@ echo "some,input,here" | gawk -f some-exercise.awk
 The tests use functions from the [bats-assert][bats-assert] library.
 Help for the various `assert*` functions can be found there.
 
+## 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 or stderr, 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 printed to the file `/dev/fd/3` will be shown during the test run but will not be included in the captured output used for assertions.
+
+Example:
+
+```awk
+BEGIN {
+    # This debug message will not interfere with test output comparison
+    print "a debug message" > "/dev/fd/3"
+
+    # Normal program output (this is what your tests will see and compare)
+    print "Hello, World!"
+}
+```
+
+Example run:
+
+```none
+$ bats test-hello-world.bats
+test-hello-world.bats
+ ✓ Say Hi!
+a debug message
+
+1 test, 0 failures
+```
+
+This allows you to see helpful debug output without affecting the tests.
+
+Hiding the details in a function may improve readability if you use it in several places in your code:
+
+```awk
+BEGIN {
+    debug("a debug message")
+    print "Hello, World!"
+}
+
+function debug(msg) {print msg > "/dev/fd/3"}
+```
+
 ## Skipped tests
 
 Solving an exercise means making all its tests pass.

From 8b640eb11984d98b7ed6287b649e865b5bb91419 Mon Sep 17 00:00:00 2001
From: Glenn Jackman <glenn.jackman@gmail.com>
Date: Thu, 18 Sep 2025 17:39:42 -0400
Subject: [PATCH 2/2] move it to the bottom

---
 exercises/shared/.docs/tests.md | 65 ++++++++++++++++++---------------
 1 file changed, 35 insertions(+), 30 deletions(-)

diff --git a/exercises/shared/.docs/tests.md b/exercises/shared/.docs/tests.md
index 9ef1995..a25d326 100644
--- a/exercises/shared/.docs/tests.md
+++ b/exercises/shared/.docs/tests.md
@@ -28,6 +28,35 @@ echo "some,input,here" | gawk -f some-exercise.awk
 The tests use functions from the [bats-assert][bats-assert] library.
 Help for the various `assert*` functions can be found there.
 
+## Skipped tests
+
+Solving an exercise means making all its tests pass.
+By default, only one test (the first one) is executed when you run the tests.
+This is intentional, as it allows you to focus on just making that one test pass.
+Once it passes, you can enable the next test by commenting out or removing the
+
+    [[ $BATS_RUN_SKIPPED == true ]] || skip
+
+annotations prepending other tests.
+
+## Overriding skips
+
+To run all tests, including the ones with `skip` annotations, you can run:
+```bash
+BATS_RUN_SKIPPED=true bats test-some-exercise.bats
+```
+
+It can be convenient to use a wrapper function to save on typing: in `bash` you can do:
+```bash
+bats() {
+    BATS_RUN_SKIPPED=true command bats *.bats
+}
+```
+Then run tests with just:
+```bash
+bats
+```
+
 ## Debugging output
 
 ```exercism/caution
@@ -69,40 +98,16 @@ Hiding the details in a function may improve readability if you use it in severa
 
 ```awk
 BEGIN {
-    debug("a debug message")
-    print "Hello, World!"
+    debug("starting ...")
 }
 
-function debug(msg) {print msg > "/dev/fd/3"}
-```
-
-## Skipped tests
-
-Solving an exercise means making all its tests pass.
-By default, only one test (the first one) is executed when you run the tests.
-This is intentional, as it allows you to focus on just making that one test pass.
-Once it passes, you can enable the next test by commenting out or removing the
-
-    [[ $BATS_RUN_SKIPPED == true ]] || skip
-
-annotations prepending other tests.
-
-## Overriding skips
+# do stuff here ...
 
-To run all tests, including the ones with `skip` annotations, you can run:
-```bash
-BATS_RUN_SKIPPED=true bats test-some-exercise.bats
-```
-
-It can be convenient to use a wrapper function to save on typing: in `bash` you can do:
-```bash
-bats() {
-    BATS_RUN_SKIPPED=true command bats *.bats
+END {
+    debug("... finished")
 }
-```
-Then run tests with just:
-```bash
-bats
+
+function debug(msg) {print msg > "/dev/fd/3"}
 ```
 
 [bash]: https://exercism.org/docs/tracks/bash/tests