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 There are multiple mechanisms to filter which tests to execute:
42 ○ --filter <regex> to filter by test name
44 ○ --filter-status <status> to filter by the test´s status in the last
46 run
47 ○ --filter-tags <tag-list> to filter by the tags of a test
49
53 Tags can be used for finegrained filtering of which tests to run via
54 --filter-tags. This accepts a comma separated list of tags. Only tests
55 that match all of these tags will be executed. For example, bats --fil‐
56 ter-tags a,b,c will pick up tests with tags a,b,c, but not tests that
57 miss one or more of those tags.
58 Additionally, you can specify negative tags via bats --filter-tags
60 a,!b,c, which now won´t match tests with tags a,b,c, due to the b, but
61 will select a,c. To put it more formally, --filter-tags is a boolean
62 conjunction.
63 To allow for more complex queries, you can specify multiple --fil‐
65 ter-tags. A test will be executed, if it matches at least one of them.
66 This means multiple --filter-tags form a boolean disjunction.
67 A query of --filter-tags a,!b --filter-tags b,c can be translated to:
69 Execute only tests that (have tag a, but not tag b) or (have tag b and
70 c).
71 An empty tag list matches tests without tags.
73
75 -c, --count
76 Count the number of test cases without running any tests
77 --code-quote-style <style>
79 A two character string of code quote delimiters or custom which
80 requires setting $BATS_BEGIN_CODE_QUOTE and
81 $BATS_END_CODE_QUOTE. Can also be set via
82 $BATS_CODE_QUOTE_STYLE.
83 -f, --filter <regex>
85 Filter test cases by names matching the regular expression
86 -F, --formatter <type>
88 Switch between formatters: pretty (default), tap (default w/o
89 term), tap13, junit, /<absolute path to formatter>
90 --filter-status <status>
92 Only run tests with the given status in the last completed (no
93 CTRL+C/SIGINT) run. Valid status values are: failed - runs tests
94 that failed or were not present in the last run missed - runs
95 tests that were not present in the last run
96 --filter-tags <comma-separated-tag-list>
98 Only run tests that match all the tags in the list (&&). You can
99 negate a tag via prepending !. Specifying this flag multiple
100 times allows for logical or (||): --filter-tags A,B --fil‐
101 ter-tags A,!C matches tags (A && B) || (A && !C)
102 --gather-test-outputs-in <directory>
104 Gather the output of failing and passing tests as files in di‐
105 rectory
106 -h, --help
108 Display this help message
109 -j, --jobs <jobs>
111 Number of parallel jobs (requires GNU parallel)
112 --no-tempdir-cleanup
114 Preserve test output temporary directory
115 --no-parallelize-across-files
117 Serialize test file execution instead of running them in paral‐
118 lel (requires --jobs >1)
119 --no-parallelize-within-files
121 Serialize test execution within files instead of running them in
122 parallel (requires --jobs >1)
123 --report-formatter <type>
125 Switch between reporters (same options as --formatter)
126 -o, --output <dir>
128 Directory to write report files
129 -p, --pretty
131 Shorthand for "--formatter pretty"
132 --print-output-on-failure
134 Automatically print the value of $output on failed tests
135 -r, --recursive
137 Include tests in subdirectories
138 --show-output-of-passing-tests
140 Print output of passing tests
141 -t, --tap
143 Shorthand for "--formatter tap"
144 -T, --timing
146 Add timing information to tests
147 -x, --trace
149 Print test commands as they are executed (like set -x)
150 --verbose-run
152 Make run print $output by default
153 -v, --version
155 Display the version number
156
158 When you run Bats from a terminal, you´ll see output as each test is
159 performed, with a check-mark next to the test´s name if it passes or an
160 "X" if it fails.
161 $ bats addition.bats
164 ✓ addition using bc
165 ✓ addition using dc
166 2 tests, 0 failures
168 If Bats is not connected to a terminal--in other words, if you run it
172 from a continuous integration system or redirect its output to a
173 file--the results are displayed in human-readable, machine-parsable TAP
174 format. You can force TAP output from a terminal by invoking Bats with
175 the --tap option.
176 $ bats --tap addition.bats
179 1..2
180 ok 1 addition using bc
181 ok 2 addition using dc
182
186 The bats interpreter exits with a value of 0 if all test cases pass, or
187 1 if one or more test cases fail.
188
190 Bats wiki: https://github.com/bats-core/bats-core/wiki/
191 bash(1), bats(7)
193
195 (c) 2017-2022 bats-core organization
196 (c) 2011-2016 Sam Stephenson
197 Bats is released under the terms of an MIT-style license.
199bats-core November 2022 BATS(1)