Bats Test Conventions

Bats Test Conventions

Bats covers the shell side of this repo (scripts, plugins, phase files). TypeScript helpers under lib/node/ use vitest instead - don't mix them. TESTING.md has the full helper catalog; this skill is the short version.

When this applies

• Adding a new .bats file for a script / plugin / phase-file change.
• Editing an existing .bats file and wondering which helper to use.
• Deciding whether a new test should be a subprocess run or a sourced unit test.

Skip this skill for *.spec.ts vitest specs - use the ts-vs-bats-router skill instead.

File path mirrors source path

The test file path is the source file path, with tests/ prepended and .bats appended:

Do NOT put tests under tests/bin/ or tests/scripts/. Reviewers expect to navigate by parallel path.

@test naming - REQUIRED prefix

Every @test block starts with the script or feature name followed by : (colon + space) and a short description. This is not optional - it's how test grep works in this repo.

@test "git-sync: prints help with -h" { ... }
@test "git-sync: restores stash on failure" { ... }
@test "10-fzf: skips when fzf binary is absent" { ... }

Derive the prefix from the source basename without extension:

That prefix makes test grep usable (./dev/test-bats-docker.sh -q | grep git-sync). Tests without the prefix pass CI but will be flagged in review.

The two-helper starting set

Every test file sources tests/helpers/common.bash. In setup(), bats' load drops the .bash extension for you, so you write load '../../helpers/common' - but when referring to the file itself in documentation or comments, always call it tests/helpers/common.bash (the actual on-disk filename):

setup() {
  load '../../helpers/common'   # bats auto-appends .bash
  setup_test_bin
  SCRIPT="${REPO_ROOT}/dotenv/bin/foo"
}

The helpers you reach for first:

Before adding a helper of your own, rg -n "^[a-z_]+ *()" tests/helpers/common.bash - odds are it exists.

Subprocess vs sourced

• Subprocess (run bash "${SCRIPT}" …). Default for end-to-end tests: argparse, help output, error exits, external-command stubs. Tests match what users see when invoking the script.
• Sourced via source_without_main. Use when unit-testing internal helper functions. Skips the script's main body so you can call the helper directly with its own args. See TESTING.md for the marker-comment convention that makes source_without_main work.

Rule of thumb: test the public CLI behavior via subprocess; test internal logic via source. Cover both for non-trivial scripts.

Stubbing externals

Any external command a script runs is a liability. Stub it.

@test "git-sync: bails when no remote is set" {
  stub_command git <<'EOF'
#!/usr/bin/env bash
case "$1" in
  remote) exit 0 ;;   # prints nothing, exits 0 → no remote
  *) echo "unexpected git call: $*" >&2; exit 2 ;;
esac
EOF

  run bash "${SCRIPT}"
  assert_failure
  assert_output --partial "no remote"
}

Never rely on the host's real git, curl, ssh, openssl, gh. Even in CI they produce different output across versions.

Assertions

bats-assert is loaded by common.bash. Use the named helpers, not raw [[ ]]:

• assert_success / assert_failure (exit-code checks).
• assert_output --partial "<text>" / assert_output "<exact>".
• assert_line "<text>" / refute_line "<text>".

Plain [ "$status" -eq 0 ] works but gives worse failure messages.

Running tests

Prefer Docker - it pins the bats / bats-assert version and sidesteps host drift.

Anti-patterns

• Tests under tests/bin/ instead of mirroring the source path. Reviewers can't find them.
• Relying on real git / curl in CI. Stub them.
• Tests that cd into the repo root without restoring $PWD. Use $BATS_TEST_TMPDIR as the working dir.
• Sharing state between @test blocks. Each @test gets a fresh $BATS_TEST_TMPDIR; if you need shared fixtures, create them in setup_file (see bats docs) or per-test in setup.
• Skipping helper reuse - writing mkdir -p "$HOME/.config" … inline when setup_isolated_home does it.
• Asserting on exact output when the script emits version-dependent strings. Use --partial.
• Inventing a new prefix style. <script>: is the repo convention.

Quick reference