Usage¶
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
with the -h
or --help
options. These are the options that Bats currently
supports:
Bats 1.5.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
-f, --filter <regex> Only run tests that match the regular expression
-F, --formatter <type> Switch between formatters: pretty (default),
tap (default w/o term), tap13, junit
--gather-test-outputs-in <directory>
Gather the output of failing *and* passing tests
as files in directory
-h, --help Display this help message
-j, --jobs <jobs> Number of parallel jobs (requires GNU parallel)
--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
-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
files. (bats
will only execute .bats
files at the top level of each
directory; it will not recurse unless you specify the -r
flag.)
Test cases from each file are run sequentially and in isolation. If all the test
cases pass, 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][TAP].
You can force TAP output from a terminal by invoking Bats with the --formatter tap
option.
$ bats --formatter tap addition.bats
1..2
ok 1 addition using bc
ok 2 addition using dc
With --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
Test reports will be output in the executing directory, but may be placed elsewhere
by specifying the --output
flag.
$ bats --formatter junit addition.bats --output /tmp
1..2
ok 1 addition using bc
ok 2 addition using dc
Parallel Execution¶
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
hardware).
Ordering of parallised tests is not guaranteed, so this mode may break suites
with dependencies between tests (or tests that write to shared locations). When
enabling --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
sequentially.
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 finegrained control, you can export BATS_NO_PARALLELIZE_WITHIN_FILE=true
in setup_file()
or outside any function to disable parallelization only within the containing file.