bash-script-tests

---
name: "bash-script-tests"
description: "Use together with bash-script-kiss when the user asks for tests for a bash script: a bats file in tests/ and fake external commands in tests/stubs/."
metadata:
  version: "1.0.0"
---

# Tests for bash scripts

This builds on `bash-script-kiss`: tests and stubs are written in English, in
the same plain style, and stubs follow its header and strict mode rules. This
skill only adds how the tests are laid out, how the fakes work and what to
test. Write tests only when the user asks for them.

## Layout

```text
mysql-backup.sh
tests/
    mysql-backup.bats       one test file per script
    stubs/
        mysqldump           one fake per external command, same name
```

Run them with `bats tests/`. They need bats 1.5 or newer
(`apt install bats` on Debian and Ubuntu).

## The test file

Start from this:

```bash
#!/usr/bin/env bats
#
# mysql-backup.bats - tests for mysql-backup.sh; a fake mysqldump keeps them offline
#
# Usage:    bats tests/mysql-backup.bats
# Requires: bats 1.5+
# Author:   Jane Doe <jane.doe@example.com>

bats_require_minimum_version 1.5.0

setup_file() {
    # Copies with their own execute bit, so a download that dropped +x doesn't matter.
    STUB_DIR="$BATS_FILE_TMPDIR/stubs"
    mkdir -p "$STUB_DIR"
    cp "$BATS_TEST_DIRNAME"/stubs/* "$STUB_DIR/"
    chmod +x "$STUB_DIR"/*
    export STUB_DIR
}

setup() {
    SCRIPT="$BATS_TEST_DIRNAME/../mysql-backup.sh"
    PATH="$STUB_DIR:$PATH"
    # Stop right here rather than let a test reach a real system.
    local cmd
    for cmd in "$STUB_DIR"/*; do
        if [ "$(command -v "${cmd##*/}")" != "$cmd" ]; then
            echo "${cmd##*/} is not the test stub" >&2
            return 1
        fi
    done
    CMD_LOG="$BATS_TEST_TMPDIR/cmd.log"
    export CMD_LOG
}

@test "unknown option is a usage error" {
    run -2 --separate-stderr "$SCRIPT" --nope
    [[ $stderr == *"unknown option: --nope"* ]]
}
```

- The header has no `Version` line; the tests go with the script's version.
- Name each test with a sentence that says what should happen.
- Always give `run` the expected exit code (`run -0`, `run -2`, ...) and
  `--separate-stderr`. Then `$output` and `$lines` are stdout and `$stderr`
  is stderr, so a test can tell data from messages.
- Check with plain `[ ]` and `[[ ]]`. No assertion library, so there's nothing
  extra to install.
- Match messages on the part that matters (`*"unknown option"*`), not the
  whole line, so rewording a message doesn't break ten tests.
- Files a test creates go in `$BATS_TEST_TMPDIR`; bats removes it.

## Stubs

A stub is a small script that pretends to be a real command, so the tests
never touch a database, the network or a real server.

```bash
#!/usr/bin/env bash
#
# mysqldump - test stand-in that prints a canned dump, no database needed
#
# Usage:    mysqldump [options] DB
# Author:   Jane Doe <jane.doe@example.com>
# Version:  1.0.0

set -o errexit -o nounset -o pipefail -o errtrace
shopt -s inherit_errexit 2>/dev/null || true

# Lets tests check the exact arguments, one per line.
if [[ -n ${CMD_LOG:-} ]]; then
    printf '%s\n' "$@" > "$CMD_LOG"
fi

case ${*: -1} in
    broken)
        printf "mysqldump: Got error: 1045: Access denied\n" >&2
        exit 2
        ;;
    *)
        printf -- '-- MySQL dump 10.13\n-- Dump completed on 2026-11-07 12:00:00\n'
        ;;
esac
```

- It picks its behaviour from the arguments (a database called `broken`, a
  server called `192.0.2.1`), so a test reads like a normal call.
- It prints what the real tool prints, on the same stream. Copy real output;
  if the tool has a quirk (errors on stdout, odd exit codes), keep it and say
  so in a comment, because that's what the script has to cope with.
- It writes its arguments to `$CMD_LOG` when that's set, so a test can check
  what the script actually called.
- It has one case for every failure the script handles: an error exit, output
  that stops halfway, and a clean exit with wrong or incomplete output.
- Use documentation addresses and names for fake data: `192.0.2.0/24`,
  `2001:db8::/32`, `example.com`.

## What to test

For every script:

- `--help` exits 0 and mentions every option
- `--version` matches the `Version` line in the header
- an unknown option and a missing argument exit 2
- a missing dependency exits 3:
  `run -3 --separate-stderr env PATH=/nonexistent /bin/bash "$SCRIPT" ...`
- sourcing doesn't run `main`:
  `run -0 --separate-stderr bash -c "source '$SCRIPT'; echo sourced"`

Then what this script is about:

- every exit code it documents
- every failure leaves nothing half done: no temp files, no partial output
  passed off as good
- anything that deletes or changes things touches only what it should, and
  `--dry-run` changes nothing
- stdout holds only data, messages go to stderr, and there are no escape
  codes when stderr isn't a terminal

Don't test colors or symbols as a terminal shows them; bats isn't a terminal.
Check those once by hand.

## When a test fails

Fix the script, not the test, unless the test itself was wrong. A fix in the
script bumps its version as `bash-script-kiss` says.

## Before you finish

- [ ] `bats tests/` passes
- [ ] `shellcheck` is clean on the stubs
- [ ] `setup` fails when a command isn't the stub
- [ ] Nothing in the tests can reach a real system