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] [FILES]

-h, --help
    Print this help and exit

-v, --version
    Print version information and exit

-c, --count
    Count test cases without running them

-f, --filter <regex>
    Run only tests matching regex

-j, --jobs <N>
    Run N test files in parallel (default: 1)

-r, --recursive
    Recursively find and run *.bats files

--formatter <name>
    Use formatter: pretty or tap (default: pretty)

--tap
    Print TAP output without summary

--show-output
    Show output for passing tests too

--timing
    Print timing summary for tests

--tap-time
    TAP output with per-test timing

Bats (Bash Automated Testing System) is a lightweight, TAP-compliant testing framework designed for Bash scripts.

It enables developers to write unit tests directly in Bash using simple functions prefixed with test_. Each test function runs independently, and Bats executes them, capturing output and exit codes to determine pass/fail status.

Key features include test filtering with regex, parallel execution via --jobs, recursive directory scanning, and multiple output formatters like pretty (default, colorized summary) or tap for CI integration. It supports timing reports, showing output for passed tests, and counting tests without execution.

Ideal for verifying script behavior in CI/CD pipelines (e.g., GitHub Actions, Jenkins). Bats requires Bash 3.2+ and installs via package managers (apt install bats) or GitHub releases. Tests are saved as executable .bats files, making it easy to version control alongside code.

Tests must be executable Bash files with functions named test_*. Parallel mode (--jobs) requires GNU parallel or compatible. Not suitable for non-Bash shells.

Write tests as test_name () { setup; run command; assertions; } using helpers like run, assert_success.

Use load '../script' to include code under test; $output and $status available post-run.

Created by Sam Stephenson in 2012 as a simple Bash testing tool. Maintained by bats-core organization since 2018, with ongoing enhancements for parallelism, formatters, and CI support. Current version ~1.10.

bash(1), prove(1), sh(1)