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 operations that can modify or delete files, upgrade packages, etc., and a failure in production can be irreversible. Unit tests let you verify the script’s logic safely before deployment.

Typical Testing Scenarios

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

Scenario 2 : Test stability depends on external services accessed via commands like curl. Network or service failures can cause flaky tests.

Scenario 3 : Execution time depends on commands such as Gradle, which may take minutes or hours, making large test suites slow.

Even when using Docker containers, these problems remain: environment preparation, external‑service stability, and command execution time.

What Is a Bash Unit Test?

A Bash unit test focuses on the script’s internal logic—verifying that the options and arguments passed to commands are as expected—while ignoring whether the external command itself succeeds.

How to Write Bash Unit Tests

The Bach Testing Framework is currently the only framework that can write true unit tests for Bash scripts. It prevents any command found in PATH from being executed, making tests fast, safe, and OS‑independent.

Simple : No installation required; just source bach.sh.

Fast : Commands are mocked, so tests run instantly.

Safe : Dangerous commands like rm -rf * are never executed.

Cross‑platform : Works on Linux, macOS, Cygwin, Git Bash, FreeBSD, etc.

Installation

source path/to/bach.sh

Example Test Case

#!/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() {
    sudo rm -rf /
}

The framework runs each test‑* function and its corresponding …‑assert function, comparing the mocked command with the expected command.

Mocking Commands

Use @mock to simulate a command’s output, e.g.:

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

For sequential mocks, use @@mock to return different results on each call.

Real‑World Adoption

Bach Testing Framework is used at BMW Group and Huawei to ensure the reliability of large‑scale build scripts.