bats

Run a BATS test script and output results in the TAP (Test Anything Protocol) format

$ bats [[-t|--tap]] [path/to/test.bats]

$ bats [[-c|--count]] [path/to/test.bats]

$ bats [[-r|--recursive]] [path/to/directory]

$ bats [[-F|--formatter]] [pretty|tap|tap13|junit] [path/to/test.bats]

$ bats [[-T|--timing]] [path/to/test.bats]

$ bats [[-j|--jobs]] [number] [path/to/test.bats]

bats [options] [test_paths...]
bats [options] [--] [arguments_to_script...]

Common Usage:
bats my_script.bats
bats --recursive my_tests_dir

--help, -h
    Displays a brief help message and exits.

--version, -v
    Prints the current Bats version and exits.

--recursive, -r
    Recursively searches for and runs all .bats files within specified directories.

--filter , -f
    Only runs tests whose descriptions match the provided extended regular expression.

--formatter
    Specifies the output formatter to use, such as tap, pretty, or junit.

--pretty
    An alias for --formatter pretty, providing human-readable output.

--tap
    An alias for --formatter tap, producing raw TAP output.

--jobs , -j
    Runs test files in parallel using up to n concurrent jobs.

--fail-fast
    Exits immediately after the first test failure is encountered.

--summary-only
    Prints only the summary of the test run, suppressing detailed test results.

--gather-test-output
    Captures and displays stdout and stderr for all tests, not just failed ones.

--skip-formatter
    Disables all formatters, outputting only raw TAP.

--load
    Loads an external shell script into the test environment before running tests.

--
    Marks the end of Bats options, allowing subsequent arguments to be passed directly to the test script being tested.

Bats is a TAP-compliant testing framework for Bash and other shell scripts. It provides a simple yet powerful way to verify that your command-line tools and scripts behave as expected. Tests are written directly in Bash, allowing for seamless integration into existing shell-based projects. Each test file is a shell script containing one or more test cases, typically defined within a 'run' block followed by assertion functions. Bats executes each test case in a separate subshell, capturing its standard output, standard error, and exit status. These captured values are then compared against expected outcomes using a rich set of built-in assertion helpers like 'assert_output', 'assert_success', and 'assert_failure'. The framework's output conforms to the standard Test Anything Protocol (TAP), making it easily parsable by continuous integration (CI) systems and other automated test runners. This makes Bats an ideal choice for ensuring the reliability and correctness of shell scripts within automated build pipelines, enabling robust development practices for command-line utilities.

Tests within Bats run in a separate subshell, meaning that environment variable changes or directory changes made during a test case do not persist across different test cases. This isolation, while beneficial for reliability, can sometimes make debugging complex multi-step interactions challenging. While primarily designed for Bash, the test logic itself must be written in Bash, even if the script being tested is in another shell. Performance might be a consideration for extremely large test suites without utilizing parallel execution (--jobs).

Bats test files typically end with the .bats extension. They are standard Bash scripts where test cases are defined using a descriptive string followed by a { ... } block containing a run command and one or more assertion calls. Common setup/teardown hooks like setup_file(), teardown_file(), setup(), and teardown() can be defined to manage test state before and after individual tests or entire test files.

Bats provides a comprehensive set of assertion functions to verify test outcomes. Key assertions include assert_output (to check the standard output against an expected string), assert_success (to verify a zero exit status), assert_failure (to verify a non-zero exit status), assert_line (to check specific lines in output), assert_equal, assert_dir_exists, and more. These simplify the process of writing robust tests without external dependencies.

Bats was initially developed by Sam Stephenson at GitHub as a lightweight solution for testing command-line utilities written in shell. Its simplicity and native Bash syntax quickly led to its adoption in various projects. Over time, the project transitioned to community maintenance under the bats-core organization, ensuring its continued development, feature enhancements, and bug fixes, solidifying its position as a leading tool for shell script testing.

shUnit2, shellcheck(1), bash(1), make(1)