diff options
| author | Craig Jennings <c@cjennings.net> | 2026-06-23 21:13:26 -0400 |
|---|---|---|
| committer | Craig Jennings <c@cjennings.net> | 2026-06-23 21:13:26 -0400 |
| commit | 36262858461711bcb104896007a513691113fee8 (patch) | |
| tree | 333cc7ea0998c43c2b6af76aa6eeb1ee3d0b0f2c /languages/bash/claude/rules/bash-testing.md | |
| parent | 71db71b9d47ffbeaf1d1c859fa3e3bebb7b2ea29 (diff) | |
| download | rulesets-36262858461711bcb104896007a513691113fee8.tar.gz rulesets-36262858461711bcb104896007a513691113fee8.zip | |
feat(languages): add bash/shell bundle
Shell-heavy projects had no bundle that fit. archangel and archsetup are bash repos, and installing elisp or python gave them the wrong language rules. I added languages/bash on the go bundle's shape.
The bundle ships bash.md and bash-testing.md rules, a PostToolUse hook that runs shellcheck on edited shell files and blocks on a violation, a shellcheck pre-commit githook, settings.json wiring, gitignore-add.txt, and a "Bash/shell project" CLAUDE.md. The hook covers .sh, .bash, and extensionless files with a shell shebang, since the CLI tools that fill a shell repo carry no extension. shellcheck is the gate. shfmt stays out of the blocking path because shell has no canonical formatting style, and forcing tabs-vs-spaces would impose a contested choice. Both the hook and the githook are shellcheck-clean against their own rule.
I extended the Makefile test target to discover languages/*/tests/*.bats, so the bundle's 8 hook tests run with the rest of the suite. The README bundle table was stale, listing elisp only. I corrected it to the five bundles now shipping.
Diffstat (limited to 'languages/bash/claude/rules/bash-testing.md')
| -rw-r--r-- | languages/bash/claude/rules/bash-testing.md | 71 |
1 files changed, 71 insertions, 0 deletions
diff --git a/languages/bash/claude/rules/bash-testing.md b/languages/bash/claude/rules/bash-testing.md new file mode 100644 index 0000000..c904927 --- /dev/null +++ b/languages/bash/claude/rules/bash-testing.md @@ -0,0 +1,71 @@ +# Bash Testing Rules + +Applies to: `**/*.bats` + +Implements the core principles from `testing.md`. All rules there apply here — +this file covers shell-specific patterns. + +## Framework: bats-core + +Use [bats-core](https://bats-core.readthedocs.io/) for shell tests. A test file +is `<thing>.bats`; each test is a `@test "description" { ... }` block; a non-zero +exit inside the block fails the test. Run a file with `bats path/to/file.bats`, +or a tree with `bats -r tests/`. + +Drive the script under test with `run`: it captures `$status` (exit code), +`$output` (combined stdout+stderr), and `$lines[]` (output split by line) +without the failure aborting the test. Assert on those. + +```bash +@test "greet: prints the name passed in" { + run bash "$SCRIPT" --name Ada + [ "$status" -eq 0 ] + [[ "$output" == *"Hello, Ada"* ]] +} +``` + +## Test the Real Script, Through Its Interface + +Run the actual script file — never copy its logic into the test. Invoke it the +way a caller does (`run bash "$SCRIPT" <args>`, or `run "$SCRIPT"` when it's +executable) and assert on exit status and output. A test that re-implements the +script's logic passes even when the script breaks. + +For a script that sources a library of functions, source the library in `setup` +and call the functions directly — that's the unit level; the `run` invocation is +the integration level. + +## Normal, Boundary, Error — the Three Categories + +Cover all three from `testing.md` per script: + +- Normal: the expected arguments and inputs produce the expected output and a + zero exit. +- Boundary: empty argument, missing optional flag, single-item vs many, + whitespace and unicode in inputs, a path with a space. +- Error: missing required argument, nonexistent input file, a dependency + absent. Assert the exit code and that the error names the problem — not the + exact wording (`testing.md`'s error-behavior rule). + +## Isolation and Determinism + +- `setup()` makes a fresh `mktemp -d` per test; `teardown()` removes it. No test + leans on another's leftovers, and tests pass in any order. +- Mock an external command by putting a stub earlier on `PATH`: write a small + script named like the command into a temp dir, `chmod +x`, and prepend that + dir to `PATH` for the `run`. This is how you simulate a tool being absent, + returning an error, or emitting canned output — without touching the network + or the real tool. +- Never hardcode dates; generate them relative to `date` (see the + `task-review-staleness.bats` pattern in this repo for relative-date fixtures). +- Mock at the boundary (network, the external CLI, the clock). Don't mock the + script's own functions — those are the work. + +## What Not to Do + +- Don't assert exact error-message prose; assert the exit code plus a value the + message must contain. +- Don't share mutable state between tests through a fixed temp path. +- Don't test that `shellcheck` or `bats` themselves work — trust the tools. +- Don't skip the error cases because the happy path passes; the error paths are + where shell scripts actually break. |
