1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
# bats-support
[](https://raw.githubusercontent.com/bats-core/bats-support/master/LICENSE)
[](https://github.com/bats-core/bats-support/releases/latest)
[](https://github.com/bats-core/bats-support/actions?query=workflow%3ATests)
`bats-support` is a supporting library providing common functions to
test helper libraries written for [Bats][bats].
Features:
- [error reporting](#error-reporting)
- [output formatting](#output-formatting)
- [language tools](#language-and-execution)
See the [shared documentation][bats-docs] to learn how to install and
load this library.
If you want to use this library in your own helpers or just want to
learn about its internals see the developer documentation in the [source
files](src).
## Error reporting
### `fail`
Display an error message and fail. This function provides a convenient
way to report failure in arbitrary situations. You can use it to
implement your own helpers when the ones available do not meet your
needs. Other functions use it internally as well.
```bash
@test 'fail()' {
fail 'this test always fails'
}
```
The message can also be specified on the standard input.
```bash
@test 'fail() with pipe' {
echo 'this test always fails' | fail
}
```
This function always fails and simply outputs the given message.
```
this test always fails
```
## Output formatting
Many test helpers need to produce human readable output. This library
provides a simple way to format simple messages and key value pairs, and
display them on the standard error.
### Simple message
Simple messages without structure, e.g. one-line error messages, are
simply wrapped in a header and a footer to help them stand out.
```
-- ERROR: assert_output --
`--partial' and `--regexp' are mutually exclusive
--
```
### Key-Value pairs
Some helpers, e.g. [assertions][bats-assert], structure output as
key-value pairs. This library provides two ways to format them.
When the value is one line long, a pair can be displayed in a columnar
fashion called ***two-column*** format.
```
-- output differs --
expected : want
actual : have
--
```
When the value is longer than one line, the key and value must be
displayed on separate lines. First, the key is displayed along with the
number of lines in the value. Then, the value, indented by two spaces
for added readability, starting on the next line. This is called
***multi-line*** format.
```
-- command failed --
status : 1
output (2 lines):
Error! Something went terribly wrong!
Our engineers are panicing... \`>`;/
--
```
Sometimes, for clarity, it is a good idea to display related values also
in this format, even if they are just one line long.
```
-- output differs --
expected (1 lines):
want
actual (3 lines):
have 1
have 2
have 3
--
```
## Language and Execution
### Restricting invocation to specific locations
Sometimes a helper may work properly only when called from a certain
location. Because it depends on variables to be set or some other side
effect.
A good example is cleaning up temporary files only if the test has
succeeded. The outcome of a test is only available in `teardown`. Thus,
to avoid programming mistakes, it makes sense to restrict such a
clean-up helper to that function.
`batslib_is_caller` checks the call stack and returns `0` if the caller
was invoked from a given function, and `1` otherwise. This function
becomes really useful with the `--indirect` option, which allows calls
through intermediate functions, e.g. the calling function may be called
from a function that was called from the given function.
Staying with the example above, the following code snippet implements a
helper that is restricted to `teardown` or any function called
indirectly from it.
```shell
clean_up() {
# Check caller.
if batslib_is_caller --indirect 'teardown'; then
echo "Must be called from \`teardown'" \
| batslib_decorate 'ERROR: clean_up' \
| fail
return $?
fi
# Body goes here...
}
```
In some cases a helper may be called from multiple locations. For
example, a logging function that uses the test name, description or
number, information only available in `setup`, `@test` or `teardown`, to
distinguish entries. The following snippet implements this restriction.
```shell
log_test() {
# Check caller.
if ! ( batslib_is_caller --indirect 'setup' \
|| batslib_is_caller --indirect "$BATS_TEST_NAME" \
|| batslib_is_caller --indirect 'teardown' )
then
echo "Must be called from \`setup', \`@test' or \`teardown'" \
| batslib_decorate 'ERROR: log_test' \
| fail
return $?
fi
# Body goes here...
}
```
<!-- REFERENCES -->
[bats]: https://github.com/bats-core/bats-core
[bats-docs]: https://github.com/bats-core/bats-docs
[bats-assert]: https://github.com/bats-core/bats-assert
|
