Day 11: ShellCheck, shfmt, bats
Goal: Make ShellCheck stricter in a targeted way, format all scripts uniformly with shfmt, test functions and tools with bats, and bundle everything in a CI script that runs before every commit. · Duration: approx. 90 min · Prerequisite: Day 10
Briefing
- Besides the standard checks, ShellCheck knows
optional checks that you turn on in
.shellcheckrc. - shfmt formats shell code the way
gofmtformats Go code: uniform indentation, one form forcase,ifand pipes. That settles discussions about style. - bats (Bash Automated Testing System) runs tests
that are themselves written in Bash:
run command, then check$status,$outputand${lines[@]}. - A CI script runs everything in a fixed order. Locally via a Git hook before every commit, in CI on every push – with the same script.
werkzeug/ci.sh ─► shellcheck -x bin/* lib/lib.sh
─► shfmt -d bin lib
─► bats tests/ (lib.bats, notes-report.bats, …)
git commit ─► .git/hooks/pre-commit ─► ci.sh
Drill 1: Stricter ShellCheck
source ~/sh-lab/setup/env.sh
cd ~/sh-lab/werkzeug
shellcheck --list-optional | grep -c '^name:'
shellcheck -x -o all bin/* lib/lib.sh | grep -oE 'SC[0-9]+ \([a-z]+\)' | sort | uniq -cExpected (the numbers depend on your scripts):
11
1 SC2249 (info)
86 SC2250 (style)
1 SC2310 (info)
18 SC2312 (info)
Turning everything on is too much: SC2250 wants ${var}
instead of $var – 86 times a pure matter of taste; SC2312
reports every command substitution in an argument. A deliberate
selection makes sense:
cat > .shellcheckrc <<'EOF'
source-path=SCRIPTDIR
# A missing *) in case is almost always a forgotten case
enable=add-default-case
# Make suppressed set -e in if/&&/|| visible
enable=check-set-e-suppressed
EOF
shellcheck -x bin/* lib/lib.sh | grep -E '^In |SC[0-9]+'Expected (shortened):
In bin/notes-add line 11:
^-------^ SC2310 (info): This func…
In bin/notes-last line 11:
^-- SC2249 (info): Consider adding a default *) case, even if it just exits wi…
- SC2249 in
notes-last: thecasedoes cover all remainders from 0 to 9, but a*)branch makes that visible to every reader. - SC2310 in
notes-add:$(notes_url)is part of a command followed by|| die. In such a branch, Bash turns offset -efor the function – if something inside it fails, nobody notices. It is harmless here, but easy to fix: the URL is determined beforehand.
sed -i 's|^ 9) curl -s -o /dev/null -A notes-last "\$url/admin" ;;$|&\n *) ;;|' \
bin/notes-last
sed -i 's|^key=.*|&\nurl=$(notes_url)|; s|"\$(notes_url)/notes")|"$url/notes")|' \
bin/notes-add
shellcheck -x bin/* lib/lib.sh && echo sauberExpected:
sauber
If there is a good reason to leave a message in place, the exception
goes directly above the line, with a justification:
# shellcheck disable=SC2310 # Fehler ist erwartet.
Save your progress? Sign up for free
Drill 2: shfmt
cat > .editorconfig <<'EOF'
[*]
indent_style = space
indent_size = 2
switch_case_indent = true
EOF
shfmt -l bin lib
shfmt -d bin/notes-check | head -12
shfmt -w bin lib && shfmt -l bin lib | wc -l
shellcheck -x bin/* lib/lib.sh && notes-check -q && echo "läuft noch"Expected:
bin/notes-add
bin/notes-aufraeumen
bin/notes-backup
bin/notes-check
bin/notes-find
bin/notes-sichern
--- bin/notes-check.orig
+++ bin/notes-check
@@ -26,7 +26,10 @@
t) timeout="$OPTARG" ;;
v) verbose=1 ;;
q) quiet=1 ;;
- h) usage; exit 0 ;;
+ h)
+ usage
+ exit 0
+ ;;
:) die "Option -$OPTARG braucht einen Wert" 2 ;;
*) die "unbekannte Option -$OPTARG (Hilfe: -h)" 2 ;;
0
läuft noch
shfmt reads its settings from .editorconfig – the same
file that editors also understand. -l lists files that
would look different, -d shows the difference,
-w writes it. Without a file extension, shfmt recognizes
scripts by their shebang.
Save your progress? Sign up for free
Drill 3: First tests with bats
cat > tests/lib.bats <<'EOF'
#!/usr/bin/env bats
# Tests for lib/lib.sh
setup() {
source "$BATS_TEST_DIRNAME/../lib/lib.sh"
}
@test "need findet vorhandene Programme" {
run need bash curl
[ "$status" -eq 0 ]
}
@test "need bricht mit Exit-Code 3 ab" {
run need gibtsnicht
[ "$status" -eq 3 ]
[[ $output == *"Programm fehlt: gibtsnicht"* ]]
}
@test "notes_url hat einen Standard" {
unset NOTES_URL
run notes_url
[ "$output" = "http://127.0.0.1:8080" ]
}
@test "retry gibt nach der erlaubten Anzahl auf" {
run retry 2 false
[ "$status" -eq 1 ]
[ "${#lines[@]}" -eq 1 ]
}
EOF
bats tests/lib.batsExpected:
lib.bats
✓ need findet vorhandene Programme
✓ need bricht mit Exit-Code 3 ab
✓ notes_url hat einen Standard
✓ retry gibt nach der erlaubten Anzahl auf
4 tests, 0 failures
runexecutes the command, captures exit code and output (stdout and stderr) and doesn’t abort the test. Afterwards you check with[ … ]or[[ … ]]– every failed check makes the test fail.setupruns before every test, and every test runs in its own shell.unset NOTES_URLonly takes effect in this test.${lines[@]}: with two attempts, there is exactly one warning.
Save your progress? Sign up for free
Drill 4: Testing a tool
notes-report needs a log with known content – a
fixture:
mkdir -p tests/fixtures
cat > tests/fixtures/access.log <<'EOF'
10.0.0.1 [02/Nov/2026:10:00:00 +0000] "GET /notes HTTP/1.1" 200 69 0.004 test
10.0.0.1 [02/Nov/2026:10:00:01 +0000] "GET /notes HTTP/1.1" 200 69 0.006 test
10.0.0.2 [02/Nov/2026:10:00:02 +0000] "POST /notes HTTP/1.1" 201 68 0.010 test
10.0.0.2 [02/Nov/2026:10:00:03 +0000] "GET /notes/7 HTTP/1.1" 404 19 0.001 test
10.0.0.3 [02/Nov/2026:10:00:04 +0000] "GET /healthz HTTP/1.1" 200 3 0.001 test
10.0.0.3 [02/Nov/2026:10:00:05 +0000] "GET /admin HTTP/1.1" 404 19 0.001 test
10.0.0.3 [02/Nov/2026:10:00:06 +0000] "GET /notes HTTP/1.1" 500 30 0.050 test
10.0.0.1 [02/Nov/2026:10:00:07 +0000] "GET /version HTTP/1.1" 200 6 0.002 test
EOF
cat > tests/notes-report.bats <<'EOF'
#!/usr/bin/env bats
# Tests for bin/notes-report
setup() {
PATH="$BATS_TEST_DIRNAME/../bin:$PATH"
fixture="$BATS_TEST_DIRNAME/fixtures/access.log"
}
@test "zählt Anfragen und Fehler" {
run notes-report "$fixture"
[ "$status" -eq 0 ]
[ "${lines[0]}" = "Anfragen: 8" ]
[ "${lines[1]}" = "Fehler: 3 (37.5 %)" ]
}
@test "findet die langsamste Anfrage" {
run notes-report "$fixture"
[[ ${lines[2]} == *'max 50.0 ms ("GET /notes")' ]]
}
@test "fasst IDs zu /notes/:id zusammen" {
run notes-report "$fixture"
[[ $output == *"/notes/:id"* ]]
[[ $output != *"/notes/7"* ]]
}
@test "leeres Log ist ein Fehler" {
run notes-report /dev/null
[ "$status" -eq 1 ]
[[ $output == *"Log ist leer"* ]]
}
EOF
bats tests/Expected:
lib.bats
✓ need findet vorhandene Programme
✓ need bricht mit Exit-Code 3 ab
✓ notes_url hat einen Standard
✓ retry gibt nach der erlaubten Anzahl auf
notes-report.bats
✓ zählt Anfragen und Fehler
✓ findet die langsamste Anfrage
✓ fasst IDs zu /notes/:id zusammen
✓ leeres Log ist ein Fehler
8 tests, 0 failures
The tests need neither notes nor Docker – only Bash and the fixture.
That way they run in any CI in seconds. Whatever works with the network
or a database gets split up: the logic in functions that can be tested
without a network, and a thin edge that only calls
curl.
Save your progress? Sign up for free
Drill 5: A CI script and a Git hook
cat > ci.sh <<'EOF'
#!/usr/bin/env bash
# ci.sh – checks the toolbox, locally and in CI
set -euo pipefail
cd "$(dirname "$(readlink -f "${BASH_SOURCE[0]}")")"
echo "== shellcheck"
shellcheck -x bin/* lib/lib.sh ci.sh
echo "== shfmt"
shfmt -d bin lib ci.sh
echo "== bats"
bats --tap tests
echo "ci: alles grün"
EOF
chmod +x ci.sh
./ci.sh | grep -E '^==|^1\.\.|ci:'
git init -q -b main
git config user.name "Lab" && git config user.email [email protected]
cat > .git/hooks/pre-commit <<'EOF'
#!/usr/bin/env bash
# only show something on errors
out=$(./ci.sh 2>&1) || { echo "$out" >&2; exit 1; }
EOF
chmod +x .git/hooks/pre-commit
git add -A && git commit -qm "Werkzeugkasten mit Tests" && git log --oneline | cut -c9-Expected:
== shellcheck
== shfmt
== bats
1..8
ci: alles grün
Werkzeugkasten mit Tests
In CI, no human is reading along: --tap switches bats to
the plain TAP format (ok 1 …, not ok 2 …) that
every CI understands. Without a terminal, bats chooses it by itself
anyway; with --tap, the output looks the same locally and
in CI.
Now the counter-test – an error that ShellCheck finds:
echo 'echo $unquoted' >> bin/hallo
git commit -qam "kaputt" 2>&1 | grep -E '^In |SC2086' | head -2
git log --oneline | wc -l
git checkout -q bin/halloExpected:
In bin/hallo line 4:
^-------^ SC2086 (info): Double quote to prevent globbing and word splitting.
1
The hook prevented the commit. In CI, the same script runs, for example in GitHub Actions:
# .github/workflows/ci.yml
name: ci
on: [push, pull_request]
jobs:
werkzeug:
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v5
- run: sudo apt-get install -y shellcheck bats
- run: |
U=https://github.com/mvdan/sh/releases/download/v3.14.1
sudo curl -fsSL -o /usr/local/bin/shfmt $U/shfmt_v3.14.1_linux_amd64
sudo chmod +x /usr/local/bin/shfmt
- run: ./ci.shSave your progress? Sign up for free
Checkpoint
~/sh-lab/werkzeug/ci.sh | tail -1Expected:
ci: alles grün
bats --count ~/sh-lab/werkzeug/testsExpected:
8
shfmt -l ~/sh-lab/werkzeug/bin ~/sh-lab/werkzeug/lib | wc -lExpected:
0
Challenge
Write tests/notes-check.bats with two tests that work
without notes running: an unknown option ends with exit code 2, and
-h prints the help and ends with 0.
Note: As in notes-report.bats,
bin/ goes to the front of PATH via
setup.
Solution
cd ~/sh-lab/werkzeug
cat > tests/notes-check.bats <<'EOF'
#!/usr/bin/env bats
# Tests for bin/notes-check, without network
setup() {
PATH="$BATS_TEST_DIRNAME/../bin:$PATH"
}
@test "unbekannte Option endet mit 2" {
run notes-check -x
[ "$status" -eq 2 ]
[[ $output == *"unbekannte Option -x"* ]]
}
@test "-h zeigt die Hilfe" {
run notes-check -h
[ "$status" -eq 0 ]
[[ ${lines[0]} == "Aufruf: notes-check"* ]]
}
EOF
./ci.sh | grep -E '^1\.\.|ci:'
git add -A && git commit -qm "Tests für notes-check" && git log --oneline | wc -lExpected:
1..10
ci: alles grün
2
Save your progress? Sign up for free
Enterprise Note
- Same versions everywhere: Pin ShellCheck, shfmt and bats in CI and use the same ones locally. A container image with all three is the simplest way.
- pre-commit framework: For teams,
pre-commit(pre-commit.com) replaces custom hooks – with ready-made entries for ShellCheck and shfmt. - Tests for scripts are not a luxury: You only notice a backup script that silently backs up nothing when you restore. Every bug fix gets a test that pins it down.