bashunit

bashunit is a fast and simple testing framework designed for Bash scripts (compatible with Bash 3.0+ on Linux, macOS, and WSL). It provides a modern suite of testing tools including:

• Assertions: Robust tools for comparing, matching, and validating results.
• Mocks and Spies: For isolating code under test.
• Data Providers: To run tests against multiple sets of data.
• Snapshots: For verifying output consistency.
• Coverage: To measure how much of your code is exercised by tests.

When reading bashunit command documentation, arguments are denoted using specific syntax:

• <arg>: A required argument that must be provided.
• [arg]: An optional argument that can be omitted (the command will use a default value if omitted).

Depending on how your code is structured, you should choose between sourcing the file or executing it as a standalone process.

Testing Individual Functions

If your script contains functions you want to test in isolation, source the script within a set_up function. This makes the functions available in the test environment's scope.

Testing Complete Scripts

If your script executes logic directly (e.g., a CLI tool), treat it as an executable. Run it using bash path/to/script.sh and capture its output to verify behavior.

# Testing functions by sourcing
function set_up() {
  source "src/calculator.sh"
}

function test_add() {
  assert_same "5" "$(add 2 3)"
}

# Testing scripts by executing
function test_deploy() {
  local output
  output=$(bash src/deploy.sh production)
  assert_contains "Deploying to production" "$output"
}

bashunit uses a hybrid approach for terminal output to balance portability and reliability:

1. Colors: Uses hardcoded ANSI escape sequences via bashunit::sgr and _BASHUNIT_COLOR_* constants. This ensures colors work even on environments where tput might fail (like TERM=dumb runners).
2. Screen Clearing: Uses bashunit::io::clear_screen, which attempts to use tput clear but falls back to the ANSI sequence \033[2J\033[H if tput is unavailable or returns no output. This is used specifically for --watch mode.
3. Color Detection: The internal function bashunit::env::supports_color is used to probe terminal capabilities, returning false if TERM=dumb or if tput colors is less than 8.

The watch subcommand no longer requires external file watchers like inotifywait or fswatch. If no watcher is installed, bashunit falls back to pure-shell polling.

You can control the polling interval using the BASHUNIT_WATCH_INTERVAL environment variable (defaults to 2 seconds).

There are specific edge cases in how bashunit calculates coverage:

• Empty Arms: An arm containing only comments or braces (no executable lines) is reported as not-taken even if the conditional was triggered.
• Implicit Else: In an if/elif chain without an explicit else, the synthetic fall-through outcome is not tracked.
• Compound Conditionals: if A && B is treated as a single binary decision rather than tracking individual sub-expressions.
• Short-circuiting: && and || operators used outside of if statements or loop-entry decisions are not tracked.

bashunit executes all functions within a test file that are prefixed with the word test.

Key rules:

• Function names must start with test to be recognized as tests.
• Function names are case-insensitive.
• You can use any valid Bash syntax to define these functions.

Functions without the test prefix are treated as auxiliary functions and will not be executed as individual tests.

function test_should_validate_an_ok_exit_code() { ... }
function testRenderAllTestsPassedWhenNotFailedTests { ... }
test_getFunctionsToRun_with_filter_should_return_matching_functions() { ... }

The bashunit source code uses a directory-based module pattern to organize large files into manageable units. Instead of a single large file or a flat list of prefixed files, modules are organized into self-contained directories. Each module must contain an index.sh file, which acts as the entry point (aggregator) for that module.

Key characteristics of this pattern:

• Predictable Entry Points: The aggregator for any module is always located at src/*/index.sh.
• Self-Contained Units: Modules are moved or removed as a single directory (e.g., mv src/module_name/ src/new_location/), preventing orphaned files.
• Discovery: The build system discovers these modules by globbing the src/*/index.sh pattern.
• Convention: This follows standard ecosystem patterns like index.ts or mod.rs.