bats(1) - f37

1BATS(1)                  Bash Automated Testing System                 BATS(1)
2
3
4

NAME

6       bats - Bash Automated Testing System
7

SYNOPSIS

9       Usage: bats [OPTIONS] tests bats [-h | -v]
10
11       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

DESCRIPTION

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
18       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
22       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
27       See bats(7) for more information on writing Bats tests.
28

RUNNING TESTS

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
35       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

OPTIONS

41       •   -c, --count: Count the number of test  cases  without  running  any
42           tests
43
44       •   --code-quote-style  <style>:  A  two character string of code quote
45           delimiters or custom which requires setting  $BATS_BEGIN_CODE_QUOTE
46           and     $BATS_END_CODE_QUOTE.     Can     also     be    set    via
47           $BATS_CODE_QUOTE_STYLE.
48
49       •   -f, --filter <regex>: Filter test cases by names matching the regu‐
50           lar expression
51
52       •   -F,  --formatter  <type>:  Switch  between  formatters: pretty (de‐
53           fault), tap (default w/o term), tap13, junit
54
55       •   --gather-test-outputs-in <directory>: Gather the output of  failing
56           and passing tests as files in directory
57
58       •   -h, --help: Display this help message
59
60       •   -j, --jobs <jobs>: Number of parallel jobs (requires GNU parallel)
61
62       •   --no-tempdir-cleanup: Preserve test output temporary directory
63
64       •   --no-parallelize-across-files Serialize test file execution instead
65           of running them in parallel (requires --jobs >1)
66
67       •   --no-parallelize-within-files Serialize test execution within files
68           instead of running them in parallel (requires --jobs >1)
69
70       •   --report-formatter  <type>:  Switch between reporters (same options
71           as --formatter)
72
73       •   -o, --output <dir>: Directory to write report files
74
75       •   -p, --pretty: Shorthand for "--formatter pretty"
76
77       •   --print-output-on-failure: Automatically print the value of $output
78           on failed tests
79
80       •   -r, --recursive: Include tests in subdirectories
81
82       •   --show-output-of-passing-tests Print output of passing tests
83
84       •   -t, --tap: Shorthand for "--formatter tap"
85
86       •   -T, --timing: Add timing information to tests
87
88       •   -x, --trace: Print test commands as they are executed (like set -x)
89
90       •   --verbose-run: Make run print $output by default
91
92       •   -v, --version: Display the version number
93
94
95

OUTPUT

97       When  you  run  Bats from a terminal, you´ll see output as each test is
98       performed, with a check-mark next to the test´s name if it passes or an
99       "X" if it fails.
100
101
102
103           $ bats addition.bats
104            ✓ addition using bc
105            ✓ addition using dc
106
107           2 tests, 0 failures
108
109
110
111       If  Bats  is not connected to a terminal--in other words, if you run it
112       from a continuous integration  system  or  redirect  its  output  to  a
113       file--the results are displayed in human-readable, machine-parsable TAP
114       format. You can force TAP output from a terminal by invoking Bats  with
115       the --tap option.
116
117
118
119           $ bats --tap addition.bats
120           1..2
121           ok 1 addition using bc
122           ok 2 addition using dc
123
124
125

EXIT STATUS

127       The bats interpreter exits with a value of 0 if all test cases pass, or
128       1 if one or more test cases fail.
129

COPYRIGHT

136       (c) 2017-2021 bats-core organization
137       (c) 2011-2016 Sam Stephenson
138
139       Bats is released under the terms of an MIT-style license.
140
141
142
143bats-core                        November 2021                         BATS(1)