🌜
🌞
bats

bats

v1.7.0

Bash Automated Testing System

npm install bats

README

Bats-core: Bash Automated Testing System

Latest release npm package License: MIT Continuous integration status Read the docs status

Join the chat in bats-core/bats-core on gitter

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" {
  result="$(echo 2+2 | bc)"
  [ "$result" -eq 4 ]
}

@test "addition using dc" {
  result="$(echo 2 2+p | dc)"
  [ "$result" -eq 4 ]
}

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 errexit (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

NOTE The documentation has moved to https://bats-core.readthedocs.io

Testing

bin/bats --tap test

See also the CI settings for the current test environment and scripts.

Support

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.

Contributing

For now see the docs folder for project guides, work with us on the wiki or look at the other communication channels.

Contact

  • You can find and chat with us on our Gitter.

Version history

See docs/CHANGELOG.md.

Background

What's the plan and why?

Tuesday, September 19, 2017:**his was forked from Bats at commit 0360811. It was created via git clone --bare and git push --mirror.

This bats-core repo is the community-maintained Bats project.

Why was this fork created?

There was an initial call for maintainers for the original Bats repository, but write access to it could not be obtained. With development activity stalled, this fork allowed ongoing maintenance and forward progress for Bats.

© 2017-2022 bats-core organization

© 2011-2016 Sam Stephenson

Bats is released under an MIT-style license; see LICENSE.md for details.

See the parent project at GitHub or the AUTHORS file for the current project maintainer team.

Release Notes

1.7.0
By Martin Schulze • Published on May 14, 2022

Bats 1.7.0

Released: 2022-05-14

Added:

  • Pretty formatter print filename when entering file (#561)
  • BATS_TEST_NAME_PREFIX allows prefixing test names on stdout and in reports (#561)
  • setup_suite and teardown_suite (#571, #585)
  • out-of-band warning infrastructure, with following warnings:
    • BW01: run command not found (exit code 127) (#586)
    • BW02: run uses flags without proper bats_require_minimum_version guard (#587)
  • bats_require_minimum_version to guard code that would not run on older versions (#587)

Documentation

  • document $BATS_VERSION (#557)
  • document new warning infrastructure (#589, #587, #586)

Fixed:

  • unbound variable errors in formatters when using SHELLOPTS=nounset (-u) (#558)
  • don't require flock and shlock for parallel mode test (#554)
  • print name of failing test when using TAP13 with timing information (#559, #555)
  • removed broken symlink, added regression test (#560)
  • don't show empty lines as # with pretty formatter (#561)
  • prevent teardown, teardown_file, and teardown_suite from overriding bats' exit code by setting $status (e.g. via calling run) (#581, #575)
    • CRITICAL: this can return exit code 0 despite failed tests, thus preventing your CI from reporting test failures! The regression happened in version 1.6.0.
  • run --keep-empty-lines now reports 0 lines on empty $output (#583)

Documentation

  • remove 2018 in title, update copyright dates in README.md (#567)
  • fix broken links (#568)
  • corrected invalid documentation of run -N (had =N instead) (#579)
    • CRITICAL: using the incorrect form can lead to silent errors. See issue #578 for more details and how to find out if your tests are affected.
1.6.1
By Martin Schulze • Published on May 13, 2022

Bats 1.6.1

Released: 2022-05-14

Fixed:

  • prevent teardown, teardown_file, and teardown_suite from overriding bats' exit code by setting $status (e.g. via calling run) (#581, #575)
    • CRITICAL: this can return exit code 0 despite failed tests, thus preventing your CI from reporting test failures! The regression happened in version 1.6.0.

Documentation

  • corrected invalid documentation of run -N (had =N instead) (#579)
    • CRITICAL: using the incorrect form can lead to silent errors. See issue #578 for more details and how to find out if your tests are affected.
1.6.0
By Martin Schulze • Published on February 24, 2022

Bats 1.6.0

Released: 2022-02-24

Added:

  • new flag --code-quote-style (and $BATS_CODE_QUOTE_STYLE) to customize quotes around code blocks in error output (#506)
  • an example/regression test for running background tasks without blocking the test run (#525, #535)
  • bats_load_library for loading libraries from the search path $BATS_LIB_PATH (#548)

Fixed:

  • improved error trace for some broken cases (#279)
  • removed leftover debug file /tmp/latch in selftest suite (single use latch) (#516)
  • fix recurring errors on CTRL+C tests with NPM on Windows in selftest suite (#516)
  • fixed leaking of local variables from debug trap (#520)
  • don't mark FD3 output from teardown_file as <failure> in junit output (#532)
  • fix unbound variable error with Bash pre 4.4 (#550)

Documentation

  • remove links to defunct freenode IRC channel (#515)
  • improved grammar (#534)
  • fixed link to TAP spec (#537)
1.5.0
By Martin Schulze • Published on October 22, 2021

Bats 1.5.0

Released: 2021-10-22

Added:

  • new command line flags (#488)
    • --verbose-run: Make run print $output by default
    • -x, --trace: Print test commands as they are executed (like set -x)`
    • --show-output-of-passing-tests: Print output of passing tests
    • --print-output-on-failure: Automatically print the value of $output on failed tests
    • --gather-test-outputs-in <directory>: Gather the output of failing and passing tests as files in directory
  • Experimental: add return code checks to run via !/-<N> (#367, #507)
  • install.sh and uninstall.sh take an optional second parameter for the lib folder name to allow for multilib install, e.g. into lib64 (#452)
  • add run flag --keep-empty-lines to retain empty lines in ${lines[@]} (#224, a894fbfa)
  • add run flag --separate-stderr which also fills $stderr and $stderr_lines (#47, 5c9b173d, #507)

Fixed:

  • don't glob run's $output when splitting into ${lines[@]} (#151, #152, #158, #156, #281, #289)
  • remove empty line after test with pretty formatter on some terminals (#481)
  • don't run setup_file/teardown_file on files without tests, e.g. due to filtering (#484)
  • print final line without newline on Bash 3.2 for midtest (ERREXIT) failures too (#495, #145)
  • abort with error on missing flock/shlock when running in parallel mode (#496)
  • improved set -u test and fixed some unset variable accesses (#498, #501)
  • shorten suite/file/test temporary folder paths to leave enough space even on restricted systems (#503)

Documentation

  • minor edits (#478)
1.4.1
By Martin Schulze • Published on July 23, 2021

Bats 1.4.1

Released: 2021-07-24

Added:

  • Docker image architectures amd64, 386, arm64, arm/v7, arm/v6, ppc64le, s390x (#438)

Fixed:

  • automatic push to Dockerhub (#438)
1.4.0
By Martin Schulze • Published on July 23, 2021

Bats 1.4.0

Released: 2021-07-23

Added:

  • added BATS_TEST_TMPDIR, BATS_FILE_TMPDIR, BATS_SUITE_TMPDIR (#413)
  • added checks and improved documentation for $BATS_TMPDIR (#410)
  • the docker container now uses tini as the container entrypoint to improve signal forwarding (#407)
  • script to uninstall bats from a given prefix (#400)
  • replace preprocessed file path (e.g. /tmp/bats-run-22908-NP0f9h/bats.23102.src) with original filename in stdout/err (but not FD3!) (#429)
  • print aborted command on SIGINT/CTRL+C (#368)
  • print error message when BATS_RUN_TMPDIR could not be created (#422)

Documentation

  • added tutorial for new users (#397)
  • fixed example invocation of docker container (#440)
  • minor edits (#431, #439, #445, #463, #464, #465)

Fixed:

  • fix bats_tap_stream_unknown: command not found with pretty formatter, when writing non compliant extended output (#412)
  • avoid collisions on $BATS_RUN_TMPDIR with --no-tempdir-cleanup and docker by using mktemp additionally to PID (#409)
  • pretty printer now puts text that is printed to FD 3 below the test name (#426)
  • rm semaphores/slot-: No such file or directory in parallel mode on MacOS (#434, #433)
  • fix YAML blocks in TAP13 formatter using ... instead of --- to start a block (#442)
  • fixed some typos in comments (#441, #447)
  • ensure /code exists in docker container, to make examples work again (#440)
  • also display error messages from free code (#429)
  • npm installed version on Windows: fix broken internal LIBEXEC paths (#459)
1.3.0
By Martin Schulze • Published on March 15, 2021

Bats 1.3.0

Released: 2021-03-08

Added:

  • custom test-file extension via BATS_FILE_EXTENSION when searching for test files in a directory (#376)
  • TAP13 formatter, including millisecond timing (#337)
  • automatic release to NPM via Github Actions (#406)

Documentation

  • added documentation about overusing run (#343)
  • improved documentation of load (#332)

Changed:

  • recursive suite mode will follow symlinks now (#370)
  • split options for (file-) --report-formatter and (stdout) --formatter (#345)
    • WARNING: This changes the meaning of --formatter junit. stdout will now show unified xml instead of TAP. From now on, please use --report-formatter junit to obtain the .xml report file!
  • removed --parallel-preserve-environment flag, as this is the default behavior (#324)
  • moved CI from Travis/Appveyor to Github Actions (#405)
  • preprocessed files are no longer removed if --no-tempdir-cleanup is specified (#395)

Documentation

Fixed:

Correctness

  • fix internal failures due to unbound variables when test files use set -u (#392)
  • fix internal failures due to changes to $PATH in test files (#387)
  • fix test duration always being 0 on busybox installs (#363)
  • fix hangs on CTRL+C (#354)
  • make BATS_TEST_NUMBER count per file again (#326)
  • include lib/ in npm package (#352)

Performance

  • don't fork bomb in parallel mode (#339)
  • preprocess each file only once (#335)
  • avoid running duplicate files n^2 times (#338)

Documentation

  • fix documentation for --formatter junit (#334)
  • fix documentation for setup_file variables (#333)
  • fix link to examples page (#331)
  • fix link to "File Descriptor 3" section (#301)
1.2.1
By Andrew Martin • Published on September 24, 2020

Released: 2020-07-06

Added:

  • JUnit output and extensible formatter rewrite (#246)
  • load function now reads from absolute and relative paths, and $PATH (#282)
  • Beginner-friendly examples in /docs/examples (#243)
  • @peshay's bats-file fork contributed to bats-core/bats-file (#276)

Changed:

  • Duplicate test names now error (previous behaviour was to issue a warning) (#286)
  • Changed default formatter in Docker to pretty by adding ncurses to Dockerfile, override with --tap (#239)
  • Replace "readlink -f" dependency with Bash solution (#217)
1.2.0
By Andrew Martin • Published on September 24, 2020

Released: 2020-04-25

Added:

  • docs/CHANGELOG.md and docs/releasing.md (#122)
  • The -f, --filter flag to run only the tests matching a regular expression (#126)
  • Optimize stack trace capture (#138)
  • --jobs n flag to support parallel execution of tests with GNU parallel (#172)

Changed:

  • AppVeyor builds are now semver-compliant (#123)
  • Add Bash 5 as test target (#181)
  • Always use upper case signal names to avoid locale dependent err… (#215)
  • Fix for tests reading from stdin (#227)
  • Fix wrong line numbers of errors in bash < 4.4 (#229)
  • Remove preprocessed source after test run (#232)
1.1.0
By Mike Bland • Published on July 9, 2018

Released: 2018-07-08

This is the first release with new features relative to the original Bats 0.4.0.

Added:

  • The -r, --recursive flag to scan directory arguments recursively for *.bats files (#109)
  • The contrib/rpm/bats.spec file to build RPMs (#111)

Changed:

  • Travis exercises latest versions of Bash from 3.2 through 4.4 (#116, #117)
  • Error output highlights invalid command line options (#45, #46, #118)
  • Replaced echo with printf (#120)

Fixed:

  • Fixed BATS_ERROR_STATUS getting lost when bats_error_trap fired multiple times under Bash 4.2.x (#110)
  • Updated bin/bats symlink resolution, handling the case on CentOS where /bin is a symlink to /usr/bin (#113, #115)

General

License
MIT
Typescript Types
None found
Tree-shakeable
No

Popularity

GitHub Stargazers
3,432
Community Interest
3,108
Number of Forks
326

Maintenance

Commits
10/219/22070
Last Commit
Open Issues
56
Closed Issues
292
Open Pull Requests
8
Closed Pull Requests
68

Versions

Versions Released
10/219/2202
Latest Version Released
May 14, 2022
Current Tags
latest1.7.0

Dependencies

Dependencies (0)
Dev Dependencies (0)

Contributors

martin-schulze-vireso
martin-schulze-vireso
Commits: 325
mbland
mbland
Commits: 128
sstephenson
sstephenson
Commits: 77
sublimino
sublimino
Commits: 41
cdevinesr
cdevinesr
Commits: 29
rockandska
rockandska
Commits: 18
jasonkarns
jasonkarns
Commits: 18
nkakouros
nkakouros
Commits: 17
btamayo
btamayo
Commits: 11
Flamefire
Flamefire
Commits: 8
cyphar
cyphar
Commits: 7
dimo414
dimo414
Commits: 5
dotmpe
dotmpe
Commits: 5
AlexSkrypnyk
AlexSkrypnyk
Commits: 4
ahippo
ahippo
Commits: 4