1BATS(1) Bash Automated Testing System BATS(1)
2
6 bats - Bash Automated Testing System
7
9 Usage: bats [OPTIONS] tests bats [-h | -v]
10 tests is the path to a Bats test file, or the path to a directory con‐
12 taining Bats test files (ending with ".bats")
13
15 Bats is a TAP-compliant testing framework for Bash. It provides a sim‐
16 ple way to verify that the UNIX programs you write behave as expected.
17 A Bats test file is a Bash script with special syntax for defining test
19 cases. Under the hood, each test case is just a function with a de‐
20 scription.
21 Test cases consist of standard shell commands. Bats makes use of Bash´s
23 errexit (set -e) option when running test cases. If every command in
24 the test case exits with a 0 status code (success), the test passes. In
25 this way, each line is an assertion of truth.
26 See bats(7) for more information on writing Bats tests.
28
30 To run your tests, invoke the bats interpreter with a path to a test
31 file. The file´s test cases are run sequentially and in isolation. If
32 all the test cases pass, bats exits with a 0 status code. If there are
33 any failures, bats exits with a 1 status code.
34 You can invoke the bats interpreter with multiple test file arguments,
36 or with a path to a directory containing multiple .bats files. Bats
37 will run each test file individually and aggregate the results. If any
38 test case fails, bats exits with a 1 status code.
39
41 • -c, --count: Count the number of test cases without running any
42 tests
43 • -f, --filter <regex>: Filter test cases by names matching the regu‐
45 lar expression
46 • -F, --formatter <type>: Switch between formatters: pretty (de‐
48 fault), tap (default w/o term), tap13, junit
49 • --gather-test-outputs-in <directory>: Gather the output of failing
51 and passing tests as files in directory
52 • -h, --help: Display this help message
54 • -j, --jobs <jobs>: Number of parallel jobs (requires GNU parallel)
56 • --no-tempdir-cleanup: Preserve test output temporary directory
58 • --no-parallelize-across-files Serialize test file execution instead
60 of running them in parallel (requires --jobs >1)
61 • --no-parallelize-within-files Serialize test execution within files
63 instead of running them in parallel (requires --jobs >1)
64 • --report-formatter <type>: Switch between reporters (same options
66 as --formatter)
67 • -o, --output <dir>: Directory to write report files
69 • -p, --pretty: Shorthand for "--formatter pretty"
71 • --print-output-on-failure: Automatically print the value of $output
73 on failed tests
74 • -r, --recursive: Include tests in subdirectories
76 • --show-output-of-passing-tests Print output of passing tests
78 • -t, --tap: Shorthand for "--formatter tap"
80 • -T, --timing: Add timing information to tests
82 • -x, --trace: Print test commands as they are executed (like set -x)
84 • --verbose-run: Make run print $output by default
86 • -v, --version: Display the version number
88
92 When you run Bats from a terminal, you´ll see output as each test is
93 performed, with a check-mark next to the test´s name if it passes or an
94 "X" if it fails.
95 $ bats addition.bats
99 ✓ addition using bc
100 ✓ addition using dc
101 2 tests, 0 failures
103 If Bats is not connected to a terminal--in other words, if you run it
107 from a continuous integration system or redirect its output to a
108 file--the results are displayed in human-readable, machine-parsable TAP
109 format. You can force TAP output from a terminal by invoking Bats with
110 the --tap option.
111 $ bats --tap addition.bats
115 1..2
116 ok 1 addition using bc
117 ok 2 addition using dc
118
122 The bats interpreter exits with a value of 0 if all test cases pass, or
123 1 if one or more test cases fail.
124
126 Bats wiki: https://github.com/bats-core/bats-core/wiki/
127 bash(1), bats(7)
129
131 (c) 2017-2021 bats-core organization
132 (c) 2011-2016 Sam Stephenson
133 Bats is released under the terms of an MIT-style license.
135bats-core August 2021 BATS(1)