Why and How to Unit Test Bash Scripts with the Bach Testing Framework

Why Write Unit Tests for Bash Scripts?

Because Bash scripts often perform OS‑level actions that can modify or delete files, upgrade packages, or otherwise cause irreversible changes, they need thorough testing before production deployment to ensure expected behavior.

Testing can be done safely in Docker containers, which isolate the environment.

Typical Scenarios

Scenario 1 : All third‑party tools used by the script must be installed beforehand (e.g., Bazel).

Scenario 2 : Test stability depends on external services accessed via commands like curl, which may fail due to network or service issues.

Scenario 3 : Execution time depends on commands such as Gradle, which can take minutes or hours.

Even with containers, preparing the environment, handling unstable services, and long execution times remain challenges.

What Is a Bash Unit Test?

A unit test should isolate commands found in PATH by mocking them, keep test cases independent, and produce the same result on different operating systems.

How to Write Bash Unit Tests

Frameworks like Bats and Shunit2 exist, but only the Bach Testing Framework can fully isolate PATH commands.

Bach’s key benefits:

Simple : No installation required.

Fast : Commands are not really executed.

Safe : Dangerous commands such as rm -rf * are never run.

Environment‑agnostic : Works on Linux, macOS, Cygwin, Git Bash, FreeBSD.

Limitations: cannot intercept absolute‑path commands or I/O redirections directly; these must be wrapped in functions and mocked.

Using Bach

Requires Bash ≥ 4.3, Coreutils and Diffutils on GNU/Linux.

Installation: download bach.sh and source it in your test script. source path/to/bach.sh Each test consists of a test‑* function and a matching *‑assert function.

#!/usr/bin/env bash
set -euo pipefail
source bach.sh

test-rm-rf() {
    project_log_path=/tmp/project/logs
    sudo rm -rf "$project_log_path/"
}

test-rm-rf-assert() {
    # This command will not really run
    sudo rm -rf /
}

Mocking is done with the @mock API, e.g.:

@mock curl --silent google.com === @stdout "baidu.com"

Repeated mocks can use @@mock to return different values on successive calls.

An example of a failing test due to missing quotes demonstrates the importance of proper quoting in Bash functions.

Bach is already used at large enterprises such as BMW Group and Huawei to ensure reliability of critical build scripts.