Unit Testing Functions with Bats-core

Bats-core (Bash Automated Testing System) is the de-facto unit testing framework for Bash. It lets you write structured, repeatable tests for your shell functions and scripts — the same way you would use JUnit for Java or pytest for Python.

• Each test is a @test block with a human-readable description.
• Tests pass when every command inside returns exit code 0.
• Tests fail on the first non-zero exit code or a failed assertion.
• Output is TAP-compatible, so CI systems (GitHub Actions, Jenkins, GitLab CI) understand it natively.

Install via your package manager or clone the repository:

A Bats test file has the extension .bats and starts with a special shebang. The core building block is the @test directive followed by a description string and a block of commands.

• The shebang #!/usr/bin/env bats tells the shell how to execute the file.
• Each @test block is an independent test case.
• You can run a single file with bats my_tests.bats or an entire directory with bats test/.

Below is the minimal structure for a Bats test file:

In real projects, your Bash functions live in library files, not inside the test file itself. Bats provides the load helper to source external files relative to the test file's directory.

• load '../lib/math.sh' sources the file before each test runs.
• After loading, all functions defined in that file are available in your test blocks.
• Keep your library functions in a lib/ directory and tests in a test/ directory for clean separation.

Example project layout and corresponding test:

The run command is the heart of Bats testing. Instead of executing a command directly, wrapping it with run captures its exit code and output without causing the test to immediately fail.

• $status — holds the exit code of the last run command.
• $output — holds the combined stdout of the last run command.
• $lines — an array where each element is one line of output (${lines[0]}, ${lines[1]}, etc.).

This lets you assert on both success and failure cases:

The built-in [ ] assertions work but give poor failure messages. The bats-assert helper library provides expressive assertion functions that print exactly what went wrong.

• assert_success — asserts $status is 0.
• assert_failure — asserts $status is non-zero.
• assert_output — asserts $output equals the given string.
• assert_output --partial — asserts the output contains the substring.
• refute_output --partial — asserts the output does NOT contain the substring.

Install by cloning bats-core/bats-assert into a test/helpers/ folder, then load it:

Bats provides two special functions — setup and teardown — that run automatically around each test. Use them to prepare and clean up shared state so each test starts with a known environment.

• setup() runs before each individual @test block.
• teardown() runs after each individual @test block, even if the test fails.
• Common uses: creating temp directories, setting environment variables, removing temp files after the test.

Sometimes you only need to set up expensive resources once per file — not before every single test. Bats provides setup_file and teardown_file for this purpose.

• setup_file() runs once before all tests in the file.
• teardown_file() runs once after all tests in the file.
• Use BATS_FILE_TMPDIR (available automatically) to share data between setup_file and your tests — regular variables won't persist across subshells.

Typical use case: starting a mock server or building a binary once, then tearing it down at the end:

A very common pattern is testing Bash functions that read from or write to the filesystem. The key technique is using temporary directories (via mktemp -d in setup) so tests never touch real files and never interfere with each other.

• Always work inside $TEST_DIR (or $BATS_TEST_TMPDIR — available automatically in recent Bats).
• Use bats-file helper library for clean file assertions like assert_file_exists and assert_file_contains.
• Never hardcode paths like /tmp/myfile — parallel test runs will collide.

Functions often call external programs like curl, aws, or git. In unit tests you want to test your logic, not the real external command. The cleanest Bats mocking technique is to define a shell function with the same name as the command inside setup — it takes precedence over the real binary.

• Define a function like curl() { echo 'mocked response'; return 0; } in setup and export it.
• Use export -f curl so the function is visible in subshells spawned by run.
• You can also write the mock to a temporary file on PATH for more complex scenarios.

Not every test can always run — sometimes you need a real network connection, a specific tool, or a certain OS. Bats provides skip to conditionally bypass a test with an informative message, instead of commenting it out or breaking the suite.

• Call skip "reason" anywhere inside a @test block to skip that test.
• Skipped tests appear in output as S and do not count as failures.
• Bats 1.5+ supports tags: annotate tests with # bats test_tags=slow,network and filter with bats --filter-tags network test/.

A well-organised Bats project follows a predictable directory layout, making it easy to onboard new contributors and integrate with CI pipelines.

Recommended structure:

• lib/ — production Bash functions (one file per concern: math.sh, fileutils.sh).
• test/ — one .bats file per library file (math.bats, fileutils.bats).
• test/helpers/ — bats-assert, bats-file, bats-support as git submodules.
• Makefile — a test target so contributors just run make test.

Run the full suite in one command:

Test your understanding of the core Bats-core testing mechanism.

In this lesson you learned how to structure and write unit tests for individual Bash functions using Bats-core. Here are the key takeaways:

• Test file structure — use the #!/usr/bin/env bats shebang and @test blocks with descriptive names.
• load — source your library files so functions are available in tests without copy-pasting.
• run + $status + $output — the core trio; always use run to capture results without causing immediate test failure.
• bats-assert — prefer assert_success, assert_failure, and assert_output over raw [ ] for readable failure messages.
• setup / teardown — run before/after each test; setup_file / teardown_file run once per file.
• Mocking — shadow external commands with same-name shell functions exported with export -f.
• skip — conditionally bypass tests that depend on unavailable resources.
• Project layout — keep lib/, test/, and test/helpers/ separated for maintainability and CI integration.

These patterns give your Bash projects the same testing discipline you would apply to any modern software project.