Testing Shell Scripts📜

Overview📜

Big Bang uses BATS (Bash Automated Testing System) to unit-test shell scripts in the repository. The primary test suites cover k3d-dev.sh, the script that automates remote k3d development environments on AWS, and quickstart.sh, the script that orchestrates quickstart provisioning, deployment, and wait flows.

These tests verify pure functions and argument parsing – no real AWS API calls, SSH connections, or network requests are made. Each test sources the script, calls a function, and checks a variable.

Optionally, Lefthook can run these tests automatically as git hooks so you catch regressions before they leave your machine.

Prerequisites📜

Install BATS📜

macOS (Homebrew):

brew install bats-core

Linux and other platforms: See the official BATS installation guide for options including apt, dnf, npm, and building from source.

Install Lefthook (optional)📜

Lefthook is not required to run BATS tests directly, but it wires them into your git workflow so they fire on commit and push.

macOS (Homebrew):

brew install lefthook

Linux and other platforms: See the Lefthook installation docs for options including apt, rpm, npm, standalone binaries, and building from source.

Running Tests📜

Run tests directly📜

bats tests/bats/k3d-dev/k3d-dev.bats

To run the quickstart suite directly:

bats tests/bats/quickstart/quickstart.bats

To run all BATS test suites recursively (useful as more suites are added):

bats --recursive tests/bats/

Run tests in parallel📜

BATS supports parallel execution with the --jobs flag when the local BATS installation has the required parallel runner available:

bats --jobs 4 --recursive tests/bats/

Expected output📜

A passing run looks like this:

k3d-dev/k3d-dev.bats
 ✓ k3dsshcmd builds correct SSH command
 ✓ set_kubeconfig uses PublicIP when not provisioning
 ✓ set_kubeconfig uses AWSUSERNAME when provisioning
 ✓ process_arguments -b sets BIG_INSTANCE=true
 ✓ process_arguments -M sets METAL_LB=false
 ✓ process_arguments -p sets PRIVATE_IP=true
 ✓ process_arguments -d sets action=destroy_instances
 ✓ process_arguments -t sets PROJECTTAG
 ✓ process_arguments -K sets RESET_K3D=true
 ✓ process_arguments -H sets PublicIP and disables cloud provisioning
 ✓ process_arguments -H without -P sets PrivateIP=PublicIP
 ✓ process_arguments -D and --domain set BASE_DOMAIN
 ✓ process_arguments handles multiple flags
 ✓ process_arguments reports unknown option
 ✓ set_domains builds PUBLIC_DOMAINS and PASSTHROUGH_DOMAINS
 ✓ set_domains uses default BASE_DOMAIN
 ✓ set_domains clears stale values before rebuilding
 ✓ run_batch_add fails if no batch started

Enabling Lefthook📜

Lefthook is opt-in. It does nothing until you explicitly install its hooks into your local clone.

One-time setup📜

lefthook install

This writes git hooks into .git/hooks/ that delegate to lefthook.yaml in the repo root. If you later want to remove them, run lefthook uninstall.

What the hooks do📜

Hook	Trigger	Runs when
`pre-commit`	`git commit`	A covered script or its matching `tests/bats/...` suite is staged
`pre-push`	`git push`	Any `.sh` or `.bats` file changed vs. the remote

The pre-commit hook runs the focused suite for the staged script, such as bats tests/bats/quickstart/quickstart.bats for quickstart.sh changes. The pre-push hook runs bats --jobs 4 --recursive tests/bats/. The glob filters mean they only fire when shell or test files are involved – a commit that only touches YAML or Markdown skips them entirely.

Running hooks manually📜

You can invoke the hooks by name without actually committing or pushing:

# Run the pre-commit hook against all files
lefthook run pre-commit --all-files

# Run the pre-push hook
lefthook run pre-push

Test structure📜

Test files live under tests/bats/, organized by the script they cover:

tests/bats/
├── k3d-dev/
│   └── k3d-dev.bats       # Tests for docs/reference/scripts/developer/k3d-dev.sh
└── quickstart/
    └── quickstart.bats    # Tests for docs/reference/scripts/quickstart.sh

Each .bats file is a valid Bash script annotated with @test blocks. Helper functions load the script under test and restore default variable state between tests so they stay independent.

The k3d-dev.sh test suite covers four areas:

Pure functions – k3dsshcmd, set_kubeconfig
Argument parsing – common flags accepted by process_arguments
Domain configuration – set_domains building FQDN lists from subdomains
Error guards – batch-file operations fail cleanly when misused

The quickstart.sh test suite covers:

Argument parsing – quickstart flags, implied flags, unknown options, and Helm passthrough arguments
Pure helpers – k3d-dev argument generation and dependency checks
Command construction – mocked k3d-dev.sh and helm invocations
Workflow orchestration – mocked destroy and deploy/wait flows without real Git, AWS, Helm, Flux, or Kubernetes calls