Add debugging output section to TESTS.md and adjust formatting by jooexploit · Pull Request #768 · exercism/bash

jooexploit · 2026-04-01T19:12:08Z

pull request template

Summary

Closes #744.

This PR documents how to print debug output while running Bash track tests with Bats without breaking output assertions.

What Changed

Added a Debugging output section to docs/TESTS.md.
Clarified that Bats captures both stdout and stderr for assertions.
Documented using file descriptor 3 (>&3) for debug messages so they are visible during local runs but excluded from asserted output.
Added note that this debugging approach is for local testing, not the Exercism online editor.

Why

Students may print debug text to stderr and see unexpected test failures. This update explains the expected behavior and recommended workflow clearly.

Testing

Docs-only change.
Content reviewed for clarity and consistency with existing track guidance.

Reviewer Resources:

Track Policies

Copilot

Pull request overview

Updates the Bash track testing documentation to improve formatting and add guidance on emitting debug output during local bats test runs.

Changes:

Reformatted the Homebrew note about installing bats-core (list formatting/indentation).
Added a new “Debugging output” section describing use of file descriptor 3 for diagnostics.
Cleaned up minor formatting (removed trailing whitespace / extra blank line).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-01T19:15:24Z

+```bash
+#!/usr/bin/env bash
+
+printf '%(%T)T -- %s\n' -1 'a debugging statement' >&3


The debugging example uses Bash’s extended printf time format (%(...)T), which is not supported in older Bash versions (notably the default Bash 3.2 on many macOS installations). Since this is a general troubleshooting tip for local runs, consider using a simpler echo/portable printf message to >&3 so the snippet works across common environments.

Suggested change

printf '%(%T)T -- %s\n' -1 'a debugging statement' >&3

printf '%s\n' 'a debugging statement' >&3

agreed. exercises/shared/.docs/tests.md uses echo.

Copilot · 2026-04-01T19:15:24Z

+When running tests, `bats` captures both stdout and stderr for output assertions.
+This means debug output printed with `echo` (stdout) or redirected to `>&2` (stderr) can cause tests to fail.
+
+For debugging, print to file descriptor `3` instead.
+`bats` reserves fd 3 for diagnostic output that is shown during test runs but not included in captured output.
+
+Example:
+
+```bash
+#!/usr/bin/env bash
+
+printf '%(%T)T -- %s\n' -1 'a debugging statement' >&3
+echo "Hello, World!"
+```
+
+Use this only when testing locally.
+The Exercism online editor does not support this style of debug output.
+


This new “Debugging output” section largely duplicates the guidance already present in exercises/shared/.docs/tests.md (including the fd 3 recommendation). To avoid the two docs drifting over time, consider keeping the wording/example in sync with the shared docs (or referencing it) so learners see consistent guidance.

Suggested change

When running tests, `bats` captures both stdout and stderr for output assertions.

This means debug output printed with `echo` (stdout) or redirected to `>&2` (stderr) can cause tests to fail.

For debugging, print to file descriptor `3` instead.

`bats` reserves fd 3 for diagnostic output that is shown during test runs but not included in captured output.

Example:

```bash

#!/usr/bin/env bash

printf '%(%T)T -- %s\n' -1 'a debugging statement' >&3

echo "Hello, World!"

```

Use this only when testing locally.

The Exercism online editor does not support this style of debug output.

Guidance on producing debug output when running `bats` tests (including the use of file descriptor `3`) is shared across exercises.

Please refer to the "Debugging output" section in the shared tests documentation (`exercises/shared/.docs/tests.md`) for the recommended approach and examples.

Copilot, the exercises/shared/.docs/tests.md file is not visible to students. That file is used in the construction of the README.md file that is part of the exercism download process.

Do we need both? I'd prefer not to duplicate large chunks of documentation.

I think it's useful to have both. These changes are for https://exercism.org/docs/tracks/bash/tests (where there are lots of instructions for testing locally) and the other are for the exercism download READM file.

Could we have one simply reference the other vs duplicating them?

We should probably create docs/DEBUGGING_LOCALLY.md

Then docs/TESTS.md and the README can both link to it. We have to assume that people working locally have an internet connection.

@jooexploit can you rework this PR to make that happen?

I ve reworked the PR as requested: I added DEBUGGING_LOCALLY.md and updated TESTS.md and README.md to link to it instead of duplicating the debugging guidance. I m going to push the updated changes now

glennj · 2026-04-01T20:19:01Z

+```
+


You need to show the bats output.

glennj · 2026-04-01T20:21:10Z

+Use this only when testing locally.
+The Exercism online editor does not support this style of debug output.


This needs to be more strongly emphasized

Suggested change

Use this only when testing locally.

The Exercism online editor does not support this style of debug output.

~~~~exercism/caution

Use this only when testing **locally**.

The Exercism online editor does not support this style of debug output.

~~~~

glennj · 2026-04-01T20:22:28Z

+When running tests, `bats` captures both stdout and stderr for output assertions.
+This means debug output printed with `echo` (stdout) or redirected to `>&2` (stderr) can cause tests to fail.
+
+For debugging, print to file descriptor `3` instead.
+`bats` reserves fd 3 for diagnostic output that is shown during test runs but not included in captured output.
+
+Example:
+
+```bash
+#!/usr/bin/env bash
+
+printf '%(%T)T -- %s\n' -1 'a debugging statement' >&3
+echo "Hello, World!"
+```
+
+Use this only when testing locally.
+The Exercism online editor does not support this style of debug output.
+


Copilot, the exercises/shared/.docs/tests.md file is not visible to students. That file is used in the construction of the README.md file that is part of the exercism download process.

…LY.md

kotp · 2026-04-01T22:19:23Z

+1 test, 0 failures
+```
+
+This is useful when you are running the tests locally. The Exercism online editor does not support this pattern.


Suggested change

This is useful when you are running the tests locally. The Exercism online editor does not support this pattern.

This is useful when you are running the tests locally.

The Exercism online editor does not support this pattern.

Still use single sentence per line style.

glennj · 2026-04-02T00:06:09Z

 bats whatever.bats
 ```

+If you want to print debug output while running the tests locally, see [Debugging Locally](DEBUGGING_LOCALLY.md).


the url would be

Suggested change

If you want to print debug output while running the tests locally, see [Debugging Locally](DEBUGGING_LOCALLY.md).

If you want to print debug output while running the tests locally, see [Debugging Locally](/docs/tracks/bash/debugging).

edit docs/config.json to add a section for this doc

{ "uuid": "${UUID}", "slug": "debugging", "path": "docs/DEBUGGING_LOCALLY.md", "title": "Debugging with `bats`", "blurb": "Debugging your Bash code while testing with bats." },

generate a uuid with bin/configlet uuid

glennj · 2026-04-02T00:06:53Z

 bats hello_world.bats
 ```

+If you need to print debug output while running tests locally, see [Debugging Locally](https://github.com/exercism/bash/blob/master/docs/DEBUGGING_LOCALLY.md).


Suggested change

If you need to print debug output while running tests locally, see [Debugging Locally](https://github.com/exercism/bash/blob/master/docs/DEBUGGING_LOCALLY.md).

If you need to print debug output while running tests locally, see [Debugging Locally](https://exercism.org/docs/tracks/bash/debugging).

Done. I updated the shared tests doc link to point to the published Exercism page at https://exercism.org/docs/tracks/bash/debugging, and I also added DEBUGGING_LOCALLY.md to config.json so it gets published at /docs/tracks/bash/debugging. The local debugging guide, TESTS.md, and README.md are all aligned now. Please take another look.

IsaacG · 2026-04-02T18:35:39Z

@@ -0,0 +1,28 @@
+# 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.


Suggested change

When you run Bash track tests with [Bats](https://github.com/bats-core/bats-core), Bats captures both stdout and stderr for output assertions.

When you run Bash track tests with [Bats](https://github.com/bats-core/bats-core), Bats captures both STDOUT and STDERR for output assertions.

IsaacG · 2026-04-02T18:36:22Z

+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 3.


Suggested change

If you want to print debug output without affecting the test result, write it to file descriptor 3.

If you want to print debug output without affecting the test result, write it to file descriptor (fd) 3.

IsaacG · 2026-04-02T18:38:43Z

 bats hello_world.bats
 ```

+If you need to print debug output while running tests locally, see [Debugging Locally](https://exercism.org/docs/tracks/bash/debugging).


Use named links similar to [tests] on line 15

I’ve updated everything you requested:

Updated wording in DEBUGGING_LOCALLY.md to use STDOUT and STDERR

Changed “file descriptor 3” to “file descriptor (fd) 3” in DEBUGGING_LOCALLY.md

Removed the repeated online editor warning at the end of DEBUGGING_LOCALLY.md

Switched the shared doc link in tests.md to a named-link format ([debugging]), similar to [tests]

…ile descriptor reference

glennj · 2026-04-04T00:42:55Z

@jooexploit here it is: https://exercism.org/docs/tracks/bash/debugging

And my mistake: it's not the exercise's README, it's the HELP.md where this shows up: https://github.com/glennj/exercism.io/blob/main/bash/hello-world/HELP.md?plain=1

Thanks for contributing!

Add debugging output section to TESTS.md and adjust formatting

775c1be

Copilot AI review requested due to automatic review settings April 1, 2026 19:12

Copilot started reviewing on behalf of jooexploit April 1, 2026 19:12 View session

Copilot AI reviewed Apr 1, 2026

View reviewed changes

glennj requested changes Apr 1, 2026

View reviewed changes

glennj requested a review from a team April 1, 2026 20:25

Add debugging guidance to README and TESTS.md; create DEBUGGING_LOCAL…

1ce5070

…LY.md

jooexploit requested a review from glennj April 1, 2026 21:26

kotp reviewed Apr 1, 2026

View reviewed changes

glennj requested changes Apr 2, 2026

View reviewed changes

Update debugging references in documentation for clarity and consistency

2164130

jooexploit requested a review from glennj April 2, 2026 12:58

IsaacG reviewed Apr 2, 2026

View reviewed changes

Improve documentation for debugging: standardize casing and clarify f…

b41d95b

…ile descriptor reference

jooexploit requested a review from IsaacG April 3, 2026 09:11

glennj approved these changes Apr 3, 2026

View reviewed changes

kotp approved these changes Apr 3, 2026

View reviewed changes

IsaacG approved these changes Apr 3, 2026

View reviewed changes

kotp merged commit 254ca88 into exercism:main Apr 4, 2026

	printf '%(%T)T -- %s\n' -1 'a debugging statement' >&3
	printf '%s\n' 'a debugging statement' >&3

		Use this only when testing locally.
		The Exercism online editor does not support this style of debug output.

	This is useful when you are running the tests locally. The Exercism online editor does not support this pattern.
	This is useful when you are running the tests locally.
	The Exercism online editor does not support this pattern.

	If you want to print debug output while running the tests locally, see [Debugging Locally](DEBUGGING_LOCALLY.md).
	If you want to print debug output while running the tests locally, see [Debugging Locally](/docs/tracks/bash/debugging).

	If you need to print debug output while running tests locally, see [Debugging Locally](https://github.com/exercism/bash/blob/master/docs/DEBUGGING_LOCALLY.md).
	If you need to print debug output while running tests locally, see [Debugging Locally](https://exercism.org/docs/tracks/bash/debugging).

		@@ -0,0 +1,28 @@
		# 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.

	If you want to print debug output without affecting the test result, write it to file descriptor 3.
	If you want to print debug output without affecting the test result, write it to file descriptor (fd) 3.

Uh oh!

Conversation

jooexploit commented Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

pull request template

Summary

What Changed

Why

Testing

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

glennj Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

glennj Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

glennj commented Apr 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jooexploit commented Apr 1, 2026 •

edited

Loading

glennj Apr 1, 2026 •

edited

Loading

glennj Apr 2, 2026 •

edited

Loading

glennj commented Apr 4, 2026 •

edited

Loading