Bats-core: Bash Automated Testing System (2018)
Bats is a TAP-compliant testing framework for Bash. It provides a simple way to verify that the UNIX programs you write behave as expected.
A Bats test file is a Bash script with special syntax for defining test cases. Under the hood, each test case is just a function with a description.
#!/usr/bin/env bats@test "addition using bc"@test "addition using dc"
Bats is most useful when testing software written in Bash, but you can use it to test any UNIX program.
Test cases consist of standard shell commands. Bats makes use of Bash's
set -e) option when running test cases. If every command in the
test case exits with a
0 status code (success), the test passes. In this way,
each line is an assertion of truth.
Table of contents
- Writing tests
- Version history
Supported Bash versions
The following is a list of Bash versions that are currently supported by Bats. This list is composed of platforms that Bats has been tested on and is known to work on without issues.
- Everything from
3.2.57(1)and higher (macOS's highest version)
- Everything from
- Arch Linux
- Alpine Linux
- Ubuntu Linux
- Windows 10
Latest version for the following Windows platforms:
- Git for Windows Bash (MSYS2 based)
- Windows Subsystem for Linux
On macOS, you can install Homebrew if you haven't already, then run:
$ brew install bats-core
You can install the Bats npm package via:
# To install globally: $ npm install -g bats # To install into your project and save it as one of the "devDependencies" in # your package.json: $ npm install --save-dev bats
Installing Bats from source
Check out a copy of the Bats repository. Then, either add the Bats
directory to your
$PATH, or run the provided
install.sh command with the
location to the prefix in which you want to install Bats. For example, to
install Bats into
$ git clone https://github.com/bats-core/bats-core.git $ cd bats-core $ ./install.sh /usr/local
Note that you may need to run
sudo if you do not have
permission to write to the installation prefix.
Running Bats in Docker
There is an official image on the Docker Hub:
$ docker run -it bats/bats:latest --version
Building a Docker image
Check out a copy of the Bats repository, then build a container image:
$ git clone https://github.com/bats-core/bats-core.git $ cd bats-core $ docker build --tag bats/bats:latest .
This creates a local Docker image called
bats/bats:latest based on Alpine
(to push to private registries, tag it with another organisation, e.g.
To run Bats' internal test suite (which is in the container image at
$ docker run -it bats/bats:latest /opt/bats/test
To run a test suite from your local machine, mount in a volume and direct Bats to its path inside the container:
$ docker run -it -v "$(pwd):/code" bats/bats:latest /code/test
This is a minimal Docker image. If more tools are required this can be used as a
base image in a Dockerfile using
FROM <Docker image>. In the future there may
be images based on Debian, and/or with more tools installed (
for example). If you require a specific configuration please search and +1 an
issue or raise a new issue.
Further usage examples are in the wiki.
Bats comes with two manual pages. After installation you can view them with
man 1 bats (usage manual) and
man 7 bats (writing test files manual). Also, you
can view the available command line options that Bats supports by calling Bats
--help options. These are the options that Bats currently
Bats x.y.z Usage: bats [-c] [-r] [-p | -t] <test> [<test> ...] <test> is the path to a Bats test file, or the path to a directory containing Bats test files. -c, --count Count the number of test cases without running any tests -h, --help Display this help message -p, --pretty Show results in pretty format (default for terminals) -r, --recursive Include tests in subdirectories -t, --tap Show results in TAP format -v, --version Display the version number
To run your tests, invoke the
bats interpreter with one or more paths to test
files ending with the
.bats extension, or paths to directories containing test
bats will not only discover
.bats files at the top level of each
directory; it will not recurse.)
Test cases from each file are run sequentially and in isolation. If all the test
bats exits with a
0 status code. If there are any failures,
bats exits with a
1 status code.
When you run Bats from a terminal, you'll see output as each test is performed, with a check-mark next to the test's name if it passes or an "X" if it fails.
$ bats addition.bats ✓ addition using bc ✓ addition using dc 2 tests, 0 failures
If Bats is not connected to a terminal—in other words, if you run it from a continuous integration system, or redirect its output to a file—the results are displayed in human-readable, machine-parsable TAP format.
You can force TAP output from a terminal by invoking Bats with the
$ bats --tap addition.bats 1..2 ok 1 addition using bc ok 2 addition using dc
Each Bats test file is evaluated n+1 times, where n is the number of test cases in the file. The first run counts the number of test cases, then iterates over the test cases and executes each one in its own process.
For more details about how Bats evaluates test files, see Bats Evaluation Process on the wiki.
run: Test other commands
Many Bats tests need to run a command and then make assertions about its exit
status and output. Bats includes a
run helper that invokes its arguments as a
command, saves the exit status and output into special global variables, and
then returns with a
0 status code so you can continue to make assertions in
your test case.
For example, let's say you're testing that the
foo command, when passed a
nonexistent filename, exits with a
1 status code and prints an error message.
@test "invoking foo with a nonexistent file prints an error"
$status variable contains the status code of the command, and the
$output variable contains the combined contents of the command's standard
output and standard error streams.
A third special variable, the
$lines array, is available for easily accessing
individual lines of output. For example, if you want to test that invoking
without any arguments prints usage information on the first line:
@test "invoking foo without arguments prints usage"
load: Share common code
You may want to share common code across multiple test files. Bats includes a
load command for sourcing a Bash source file relative to the
location of the current test file. For example, if you have a Bats test in
test/foo.bats, the command
will source the script
test/test_helper.bash in your test file. This can be
useful for sharing functions to set up your environment or load fixtures.
skip: Easily skip tests
Tests can be skipped by using the
skip command at the point in a test you wish
@test "A test I don't want to execute for now"
Optionally, you may include a reason for skipping:
@test "A test I don't want to execute for now"
Or you can skip conditionally:
@test "A test which should run"
teardown: Pre- and post-test hooks
You can define special
teardown functions, which run before and
after each test case, respectively. Use these to load fixtures, set up your
environment, and clean up when you're done.
Code outside of test cases
You can include code in your test file outside of
@test functions. For
example, this may be useful if you want to check for dependencies and fail
immediately if they're not present. However, any output that you print in code
teardown functions must be redirected to
>&2). Otherwise, the output may cause Bats to fail by polluting the
TAP stream on
File descriptor 3 (read this if Bats hangs)
Bats makes a separation between output from the code under test and output that forms the TAP stream (which is produced by Bats internals). This is done in order to produce TAP-compliant output. In the Printing to the terminal section, there are details on how to use file descriptor 3 to print custom text properly.
A side effect of using file descriptor 3 is that, under some circumstances, it
can cause Bats to block and execution to seem dead without reason. This can
happen if a child process is spawned in the background from a test. In this
case, the child process will inherit file descriptor 3. Bats, as the parent
process, will wait for the file descriptor to be closed by the child process
before continuing execution. If the child process takes a lot of time to
complete (eg if the child process is a
sleep 100 command or a background
service that will run indefinitely), Bats will be similarly blocked for the same
amount of time.
To prevent this from happening, close FD 3 explicitly when running any command
that may launch long-running child processes, e.g.
command_name 3>- &.
Printing to the terminal
Bats produces output compliant with version 12 of the TAP protocol. The
produced TAP stream is by default piped to a pretty formatter for human
consumption, but if Bats is called with the
-t flag, then the TAP stream is
directly printed to the console.
This has implications if you try to print custom text to the terminal. As
mentioned in File descriptor 3, bats provides a special
&3, that you should use to print your custom text. Here are
some detailed guidelines to refer to:
Printing from within a test function:
To have text printed from within a test function you need to redirect the output to file descriptor 3, eg
echo 'text' >&3. This output will become part of the TAP stream. You are encouraged to prepend text printed this way with a hash (eg
echo '# text' >&3) in order to produce 100% TAP compliant output. Otherwise, depending on the 3rd-party tools you use to analyze the TAP stream, you can encounter unexpected behavior or errors.
The pretty formatter that Bats uses by default to process the TAP stream will filter out and not print text output to file descriptor 3.
Text that is output directly to stdout or stderr (file descriptor 1 or 2), ie
echo 'text'is considered part of the test function output and is printed only on test failures for diagnostic purposes, regardless of the formatter used (TAP or pretty).
Printing from within the
teardownfunctions: The same hold true as for printing with test functions.
Printing outside test or
Regardless of where text is redirected to (stdout, stderr or file descriptor 3) text is immediately visible in the terminal.
Text printed in such a way, will disable pretty formatting. Also, it will make output non-compliant with the TAP spec. The reason for this is that each test file is evaluated n+1 times (as metioned earlier). The first run will cause such output to be produced before the plan line is printed, contrary to the spec that requires the plan line to be either the first or the last line of the output.
Due to internal pipes/redirects, output to stderr is always printed first.
There are several global variables you can use to introspect on Bats tests:
$BATS_TEST_FILENAMEis the fully expanded path to the Bats test file.
$BATS_TEST_DIRNAMEis the directory in which the Bats test file is located.
$BATS_TEST_NAMESis an array of function names for each test case.
$BATS_TEST_NAMEis the name of the function containing the current test case.
$BATS_TEST_DESCRIPTIONis the description of the current test case.
$BATS_TEST_NUMBERis the (1-based) index of the current test case in the test file.
$BATS_TMPDIRis the location to a directory that may be used to store temporary files.
The Bats source code repository is hosted on GitHub. There you can file bugs on the issue tracker or submit tested pull requests for review.
For real-world examples from open-source projects using Bats, see Projects Using Bats on the wiki.
To learn how to set up your editor for Bats syntax highlighting, see Syntax Highlighting on the wiki.
Bats is SemVer compliant.
1.1.0 (July 8, 2018)
This is the first release with new features relative to the original Bats 0.4.0.
-r, --recursiveflag to scan directory arguments recursively for
contrib/rpm/bats.specfile to build RPMs (#111)
- Travis exercises latest versions of Bash from 3.2 through 4.4 (#116, #117)
- Error output highlights invalid command line options (#45, #46, #118)
BATS_ERROR_STATUSgetting lost when
bats_error_trapfired multiple times under Bash 4.2.x (#110)
bin/batssymlink resolution, handling the case on CentOS where
/binis a symlink to
1.0.2 (June 18, 2018)
- Fixed sstephenson/bats#240, whereby
skipmessages containing parentheses were truncated (#48)
- Doc improvements:
- Docker usage (#94)
- Better README badges (#101)
- Better installation instructions (#102, #104)
- Packaging/installation improvements:
- package.json update (#100)
1.0.1 (June 9, 2018)
- Fixed a
BATS_CWDbug introduced in #91 whereby it was set to the parent of
PWD, when it should've been set to
PWDitself (#98). This caused file names in stack traces to contain the basename of
PWDas a prefix, when the names should've been purely relative to
- Ensure the last line of test output prints when it doesn't end with a newline
(#99). This was a quasi-bug introduced by replacing
1.0.0 (June 8, 2018)
1.0.0 generally preserves compatibility with
0.4.0, but with some Bash
compatibility improvements and a massive performance boost. In other words:
- all existing tests should remain compatible
- tests that might've failed or exhibited unexpected behavior on earlier versions of Bash should now also pass or behave as expected
- Added support for Docker.
- Added support for test scripts that have the unofficial strict mode enabled.
- Improved stability on Windows and macOS platforms.
- Massive performance improvements, especially on Windows (#8)
- Workarounds for inconsistent behavior between Bash versions (#82)
- Workaround for preserving stack info after calling an exported function under Bash < 4.4 (#87)
- Fixed TAP compliance for skipped tests
- Added support for tabs in test names.
install.shnow work reliably on Windows (#91)
0.4.0 (August 13, 2014)
- Improved the display of failing test cases. Bats now shows the source code of failing test lines, along with full stack traces including function names, filenames, and line numbers.
- Improved the display of the pretty-printed test summary line to include the number of skipped tests, if any.
- Improved the speed of the preprocessor, dramatically shortening test and suite startup times.
- Added support for absolute pathnames to the
- Added support for single-line
- Added bats(1) and bats(7) manual pages.
- Modified the
batscommand to default to TAP output when the
$CIvariable is set, to better support environments such as Travis CI.
0.3.1 (October 28, 2013)
- Fixed an incompatibility with the pretty formatter in certain environments such as tmux.
- Fixed a bug where the pretty formatter would crash if the first line of a test file's output was invalid TAP.
0.3.0 (October 21, 2013)
- Improved formatting for tests run from a terminal. Failing tests are now
colored in red, and the total number of failing tests is displayed at the end
of the test run. When Bats is not connected to a terminal (e.g. in CI runs),
or when invoked with the
--tapflag, output is displayed in standard TAP format.
- Added the ability to skip tests using the
- Added a message to failing test case output indicating the file and line number of the statement that caused the test to fail.
- Added "ad-hoc" test suite support. You can now invoke
batswith multiple filename or directory arguments to run all the specified tests in aggregate.
- Added support for test files with Windows line endings.
- Fixed regular expression warnings from certain versions of Bash.
- Fixed a bug running tests containing lines that begin with
0.2.0 (November 16, 2012)
- Added test suite support. The
batscommand accepts a directory name containing multiple test files to be run in aggregate.
- Added the ability to count the number of test cases in a file or suite by
- Preprocessed sources are cached between test case runs in the same file for better performance.
0.1.0 (December 30, 2011)
- Initial public release.
Why was this fork created?
The original Bats repository needed new maintainers, and has not been actively maintained since 2013. While there were volunteers for maintainers, attempts to organize issues, and outstanding PRs, the lack of write-access to the repo hindered progress severely.
What's the plan and why?
The rough plan, originally outlined here is to create a new, mirrored mainline (this repo!). An excerpt:
1. Roadmap 1.0: There are already existing high-quality PRs, and often-requested features and issues, especially here at #196. Leverage these and consolidate into a single roadmap.
2. Create or choose a fork or mirror of this repo to use as the new mainline: Repoint existing PRs (whichever ones are possible) to the new mainline, get that repo to a stable 1.0. IMO we should create an organization and grant 2-3 people admin and write access.
Doing it this way accomplishes a number of things:
- Removes the dependency on the original maintainer
- Enables collaboration and contribution flow again
- Allows the possibility of merging back to original, or merging from original if or when the need arises
- Prevents lock-out by giving administrative access to more than one person, increases transferability
- We are
© 2018 bats-core organization
© 2014 Sam Stephenson
Bats is released under an MIT-style license; see
LICENSE.md for details.