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 1.10.0 Usage: bats [OPTIONS] <tests> bats [-h | -v] <tests> is the path to a Bats test file, or the path to a directory containing Bats test files (ending with ".bats") -c, --count Count test cases without running any tests --code-quote-style <style> A two character string of code quote delimiters or 'custom' which requires setting $BATS_BEGIN_CODE_QUOTE and $BATS_END_CODE_QUOTE. Can also be set via $BATS_CODE_QUOTE_STYLE --line-reference-format Controls how file/line references e.g. in stack traces are printed: - comma_line (default): a.bats, line 1 - colon: a.bats:1 - uri: file:///tests/a.bats:1 - custom: provide your own via defining bats_format_file_line_reference_custom with parameters <filename> <line>, store via `printf -v "$output"` -f, --filter <regex> Only run tests that match the regular expression --filter-status <status> Only run tests with the given status in the last completed (no CTRL+C/SIGINT) run. Valid <status> values are: failed - runs tests that failed or were not present in the last run missed - runs tests that were not present in the last run --filter-tags <comma-separated-tag-list> Only run tests that match all the tags in the list (&&). You can negate a tag via prepending '!'. Specifying this flag multiple times allows for logical or (||): `--filter-tags A,B --filter-tags A,!C` matches tags (A && B) || (A && !C) -F, --formatter <type> Switch between formatters: pretty (default), tap (default w/o term), tap13, junit, /<absolute path to formatter> --gather-test-outputs-in <directory> Gather the output of failing *and* passing tests as files in directory (if existing, must be empty) -h, --help Display this help message -j, --jobs <jobs> Number of parallel jobs (requires GNU parallel or shenwei356/rush) --parallel-binary-name Name of parallel binary --no-tempdir-cleanup Preserve test output temporary directory --no-parallelize-across-files Serialize test file execution instead of running them in parallel (requires --jobs >1) --no-parallelize-within-files Serialize test execution within files instead of running them in parallel (requires --jobs >1) --report-formatter <type> Switch between reporters (same options as --formatter) -o, --output <dir> Directory to write report files (must exist) -p, --pretty Shorthand for "--formatter pretty" --print-output-on-failure Automatically print the value of `$output` on failed tests -r, --recursive Include tests in subdirectories --show-output-of-passing-tests Print output of passing tests -t, --tap Shorthand for "--formatter tap" -T, --timing Add timing information to tests -x, --trace Print test commands as they are executed (like `set -x`) --verbose-run Make `run` print `$output` by default -v, --version Display the version number For more information, see https://github.com/bats-core/bats-core
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 only execute
.bats files at the top level of each
directory; it will not recurse unless you specify the
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 --formatter tap addition.bats 1..2 ok 1 addition using bc ok 2 addition using dc
--formatter junit, it is possible
to output junit-compatible report files.
$ bats --formatter junit addition.bats 1..2 ok 1 addition using bc ok 2 addition using dc
If you have your own formatter, you can use an absolute path to the executable to use it:
$ bats --formatter /absolute/path/to/my-formatter addition.bats addition using bc WORKED addition using dc FAILED
You can also generate test report files via
--report-formatter which accepts
the same options as
--formatter. By default, the file is stored in the current
workdir. However, it may be placed elsewhere by specifying the
$ bats --report-formatter junit addition.bats --output /tmp 1..2 ok 1 addition using bc ok 2 addition using dc $ cat /tmp/report.xml <?xml version="1.0" encoding="UTF-8"?> <testsuites time="0.073"> <testsuite name="addition.bats" tests="2" failures="0" errors="0" skipped="0"> <testcase classname="addition.bats" name="addition using bc" time="0.034" /> <testcase classname="addition.bats" name="addition using dc" time="0.039" /> </testsuite> </testsuites>
New in version 1.0.0.
By default, Bats will execute your tests serially. However, Bats supports
parallel execution of tests (provided you have GNU parallel or
a compatible replacement installed) using the
--jobs parameter. This can
result in your tests completing faster (depending on your tests and the testing
Ordering of parallelised tests is not guaranteed, so this mode may break suites
with dependencies between tests (or tests that write to shared locations). When
--jobs for the first time be sure to re-run bats multiple times to
identify any inter-test dependencies or non-deterministic test behaviour.
When parallelizing, the results of a file only become visible after it has been finished.
You can use
--no-parallelize-across-files to get immediate output at the cost of reduced
overall parallelity, as parallelization will only happen within files and files will be run
If you have files where tests within the file would interfere with each other, you can use
--no-parallelize-within-files to disable parallelization within all files.
If you want more fine-grained control, you can
export BATS_NO_PARALLELIZE_WITHIN_FILE=true in
or outside any function to disable parallelization only within the containing file.