Welcome to bats-core’s documentation!

Versions before v1.2.1 are documented over there.

Contents:

• Tutorial
  • Quick installation
  • Your first test
  • Let’s do some setup
  • Dealing with output
  • Cleaning up your mess
  • Test what you can
  • Setting up a multifile test suite
  • Avoiding costly repeated setups
• Installation
  • Supported Bash versions
  • Homebrew
  • npm
  • Installing Bats from source
  • Installing Bats from source onto Windows Git Bash
  • Running Bats in Docker
• Usage
  • Parallel Execution
• Docker Usage Guide
  • Basic Usage
  • Docker Gotchas
  • Extending from the base image
• Writing tests
  • Tagging tests
  • Comment syntax
  • run: Test other commands
  • load: Share common code
  • bats_load_library: Load system wide libraries
  • skip: Easily skip tests
  • setup and teardown: Pre- and post-test hooks
  • bats_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.