bats(7) - f33

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

NAME

6       bats - Bats test file format
7

DESCRIPTION

9       A Bats test file is a Bash script with special syntax for defining test
10       cases. Under the hood, each  test  case  is  just  a  function  with  a
11       description.
12
13
14
15           #!/usr/bin/env bats
16
17           @test "addition using bc" {
18             result="$(echo 2+2 | bc)"
19             [ "$result" -eq 4 ]
20           }
21
22           @test "addition using dc" {
23             result="$(echo 2 2+p | dc)"
24             [ "$result" -eq 4 ]
25           }
26
27
28
29       Each  Bats  test  file is evaluated n+1 times, where n is the number of
30       test cases in the file. The first run counts the number of test  cases,
31       then  iterates  over  the  test  cases and executes each one in its own
32       process.
33

THE RUN HELPER

35       Many Bats tests need to run a command and then  make  assertions  about
36       its exit status and output. Bats includes a run helper that invokes its
37       arguments as a command, saves the exit status and output  into  special
38       global variables, and then returns with a 0 status code so you can con‐
39       tinue to make assertions in your test case.
40
41       For example, let´s say you´re testing that the foo command, when passed
42       a  nonexistent filename, exits with a 1 status code and prints an error
43       message.
44
45
46
47           @test "invoking foo with a nonexistent file prints an error" {
48             run foo nonexistent_filename
49             [ "$status" -eq 1 ]
50             [ "$output" = "foo: no such file ´nonexistent_filename´" ]
51           }
52
53
54
55       The $status variable contains the status code of the command,  and  the
56       $output  variable contains the combined contents of the command´s stan‐
57       dard output and standard error streams.
58
59       A third special variable, the $lines array,  is  available  for  easily
60       accessing  individual lines of output. For example, if you want to test
61       that invoking foo without any arguments prints usage information on the
62       first line:
63
64
65
66           @test "invoking foo without arguments prints usage" {
67             run foo
68             [ "$status" -eq 1 ]
69             [ "${lines[0]}" = "usage: foo <filename>" ]
70           }
71
72
73

THE LOAD COMMAND

75       You  may  want  to  share  common code across multiple test files. Bats
76       includes a convenient load command for sourcing a Bash source file rel‐
77       ative  to  the  location  of the current test file. For example, if you
78       have a Bats test in test/foo.bats, the command
79
80
81
82           load test_helper
83
84
85
86       will source the script test/test_helper.bash in your  test  file.  This
87       can  be useful for sharing functions to set up your environment or load
88       fixtures.
89

THE SKIP COMMAND

91       Tests can be skipped by using the skip command at the point in  a  test
92       you wish to skip.
93
94
95
96           @test "A test I don´t want to execute for now" {
97             skip
98             run foo
99             [ "$status" -eq 0 ]
100           }
101
102
103
104       Optionally, you may include a reason for skipping:
105
106
107
108           @test "A test I don´t want to execute for now" {
109             skip "This command will return zero soon, but not now"
110             run foo
111             [ "$status" -eq 0 ]
112           }
113
114
115
116       Or you can skip conditionally:
117
118
119
120           @test "A test which should run" {
121             if [ foo != bar ]; then
122               skip "foo isn´t bar"
123             fi
124
125             run foo
126             [ "$status" -eq 0 ]
127           }
128
129
130

SETUP AND TEARDOWN FUNCTIONS

132       You  can  define  special setup and teardown functions which run before
133       and after each test case, respectively. Use these to load fixtures, set
134       up your environment, and clean up when you´re done.
135

CODE OUTSIDE OF TEST CASES

137       You  can include code in your test file outside of @test functions. For
138       example, this may be useful if you want to check for  dependencies  and
139       fail  immediately  if they´re not present. However, any output that you
140       print in code outside of @test, setup or  teardown  functions  must  be
141       redirected  to  stderr  (>&2).  Otherwise, the output may cause Bats to
142       fail by polluting the TAP stream on stdout.
143

SPECIAL VARIABLES

145       There are several global variables you can use to  introspect  on  Bats
146       tests:
147
148       ·   $BATS_TEST_FILENAME  is  the  fully  expanded path to the Bats test
149           file.
150
151       ·   $BATS_TEST_DIRNAME is the directory in which the Bats test file  is
152           located.
153
154       ·   $BATS_TEST_NAMES is an array of function names for each test case.
155
156       ·   $BATS_TEST_NAME  is the name of the function containing the current
157           test case.
158
159       ·   $BATS_TEST_DESCRIPTION is the description of the current test case.
160
161       ·   $BATS_TEST_NUMBER is the (1-based) index of the current  test  case
162           in the test file.
163
164       ·   $BATS_SUITE_TEST_NUMBER  is the (1-based) index of the current test
165           case in the test suite (over all files).
166
167       ·   $BATS_TMPDIR is the location to a directory that  may  be  used  to
168           store temporary files.
169
170       ·   $BATS_FILE_EXTENSION  (default:  bats)  specifies  the extension of
171           test files that should be found when running a suite (via bats [-r]
172           suite_folder/)
173
174
175