Welcome to bats-core’s documentation!¶
Bats (Bash Automated Testing System) is a TAP-compliant testing framework for Bash 3.2 or above. It provides a simple way to verify that the UNIX programs you write behave as expected.
Bats is most useful when testing software written in Bash, but you can use it to test any UNIX program.
Versions before v1.2.1 are documented over in docs/versions.md.
Contents:
- Tutorial
- Installation
- Usage
- Docker Usage Guide
- Writing tests
- Tagging tests
- Comment syntax
run: Test other commandsbats_pipe: Run commands with pipesload: Share common codebats_load_library: Load system wide librariesskip: Easily skip testssetupandteardown: Pre- and post-test hooksbats_require_minimum_version <Bats version number>- Code outside of test cases
- File descriptor 3 (read this if Bats hangs)
- Printing to the terminal
- Special variables
- Libraries and Add-ons
- Gotchas
- My test fails although I return true?
- My negated statement (e.g. ! true) does not fail the test, even when it should.
- I cannot register a test multiple times via for loop.
- I cannot pass parameters to test or .bats files.
- Why can’t my function return results via a variable when using run?
- run doesn’t fail, although the same command without run does.
- load won’t load my .sh files.
- I can’t lint/shell-format my bats tests.
- The output (stdout/err) from commands under run is not visible in failed tests.
- My piped command does not work under run.
- [[ ]] (or (( )) did not fail my test
- Background tasks prevent the test run from terminating when finished
- FAQ
- How do I set the working directory?
- How do I see the output of the command under run when a test fails?
- Can I use –filter to exclude files/tests?
- How can I exclude a single test from a test run?
- How can I exclude all tests of a file from a test run?
- How can I include my own .sh files for testing?
- How can I debug a failing test?
- Is there a mechanism to add file/test specific functionality to a common setup function?
- How can I use helper libraries like bats-assert?
- How to set a test timeout in bats?
- How can I lint/shell-format my bats tests?
- How can I check if a test failed/succeeded during teardown?
- How can I setup/cleanup before/after all tests?
- Warnings
- BW01: run’s command <command> exited with code 127, indicating ‘Command not found’. Use run’s return code checks, e.g. run -127, to fix this message.
- BW02: <feature> requires at least BATS_VERSION=<version>. Use bats_require_minimum_version <version> to fix this message.
- BW03: setup_suite is visible to test file ‘<path>’, but was not executed. It belongs into ‘setup_suite.bash’ to be picked up automatically.
- Support Matrix
