Debian Codegraph @

subprojects/mutest/docs/mutest.md.html

raw
1 <meta charset="utf-8"><link rel="stylesheet" href="apidoc.css"/>
2
3 **µTest — A small C testing library**
4
5 ## What is µTest?
6
7 µTest aims to be a small unit testing library for C projects, with an API
8 heavily modelled on high level [Behavior-Driven Development][bdd] frameworks
9 like [Jasmine][jasmine] or [Mocha][mocha].
10
11 [bdd]: https://en.wikipedia.org/wiki/Behavior-driven_development
12 [jasmine]: https://jasmine.github.io/
13 [mocha]: https://mochajs.org/
14
15 ## Adding µTest to your project
16
17 The preferred way to use µTest is to include it in your own projects using
18 a Git sub-module, and then building µTest as a static library. If you are
19 using [Meson](http://mesonbuild.com), you can use a wrap file in the
20 `subprojects` directory:
21
22 ```
23 [wrap-git]
24 directory=mutest
25 url=https://github.com/ebassi/mutest.git
26 revision=master
27 ```
28
29 and then use the `fallback` dependency type:
30
31 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
32 mutest_dep = dependency('mutest-1',
33 fallback: [ 'mutest', 'mutest_dep' ],
34 default_options: ['static=true'],
35 required: false,
36 disabler: true,
37 )
38 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
39
40 !!! Note
41 The `static` option will build µTest as an uninstalled static library.
42 You can remove the `default_options` argument to get an installed
43 shared library.
44
45 µTest can also build a shared library and a [pkg-config](https://www.freedesktop.org/wiki/Software/pkg-config/)
46 file to describe the necessary compiler and linker flags, if you want to
47 install µTest in your library path; if you decide to depend on the shared
48 library, you can use the normal `pkg-config`-based dependency discovery.
49 For instance, if you are using [Meson](http://mesonbuild.com):
50
51 ```meson
52 mutest_dep = dependency('mutest-1')
53 ```
54
55 And if you're using Autotools:
56
57 ```m4
58 PKG_CHECK_MODULES(MUTEST, [mutest-1])
59 AC_SUBST(MUTEST_CFLAGS)
60 AC_SUBST(MUTEST_LIBS)
61 ```
62
63 ## Writing tests using µTest
64
65 Writing a test program using µTest requires initializing the test framework,
66 defining the various tests, and gathering the results. For convenience, µTest
67 provides a simple macro meant to replace the `main` entry point of any C
68 binary:
69
70 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
71 MUTEST_MAIN (
72 // your code goes here
73 )
74 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
75
76 The `MUTEST_MAIN` macro will initialize µTest and print the report.
77
78 Each µTest-based test starts from a *suite*, which is created by calling
79 `mutest_describe()` in the main entry point of your test binary:
80
81 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
82 MUTEST_MAIN (
83 mutest_describe ("A test suite", main_suite);
84 )
85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
86
87 A test binary can have multiple suites.
88
89 The purpose of the `main_suite()` function is to create a *specification*,
90 or *spec*. A spec describes an aspect of your data type, service, or API.
91 Each spec is made of various expectations, which are defined by calling
92 `mutest_it()`:
93
94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
95 static void
96 main_suite (void)
97 {
98 mutest_it ("is made of at least one spec", first_spec);
99 mutest_it ("can contain multiple specs", second_spec);
100 mutest_it ("can have specs that can be skipped", skipped_spec);
101 }
102 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
103
104 As you can see, the description of suites and specs tries to match a
105 natural language description of what the suite is about, and what aspect
106 of the API is covered by each spec. The descriptions will be logged in
107 the test output.
108
109 Inside each spec we have *expectations* that must be satisfied, in order
110 to say that the test suite is successful. An expectation is made of
111 three parts:
112
113 - a description of the expectation
114 - the value we are testing
115 - a *matcher function*, which will compare the value we are testing
116 with the expected value
117
118 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
119 static void
120 first_spec (void)
121 {
122 bool a = true;
123
124 mutest_expect ("a to be true", mutest_bool_value (a),
125 mutest_to_be, true, NULL);
126 mutest_expect ("a not to be false", mutest_bool_value (a),
127 mutest_not, mutest_to_be, false,
128 NULL);
129 }
130 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
131
132 Expectations can chain multiple matching functions in order to
133 create multiple conditions that must be all satisfied:
134
135 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
136 static void
137 second_spec (void)
138 {
139 // The get_greeting() function is defined elsewhere, and
140 // we are testing its output
141 const char *str = get_greeting ();
142
143 mutest_expect ("get_greeting() to return all parts of a greeting",
144 mutest_string_value (str),
145 mutest_to_start_with_string, "hello",
146 mutest_to_contain, ",",
147 mutest_to_end_with_string, "world",
148 NULL);
149 }
150 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
151
152 In the example above, the expectation will only be satisfied if all three
153 matchers are successful.
154
155 Expectations can be programmatically skipped. For instance, if you haven't
156 implemented some functionality, yet. These expectations will be satisfied,
157 but still logged not as successes:
158
159 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
160 static void
161 skipped_spec (void)
162 {
163 // The get_answer() function is defined elsewhere
164 int answer = get_answer ();
165
166 mutest_expect ("an answer to the ultimate question of life, the universe, and everything",
167 mutest_int_value (answer),
168 mutest_skip, "Deep Thought hasn't finished yet",
169 NULL);
170 }
171 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
172
173 In the example above, the `skipped_spec()` specification will succeed, but
174 it will be marked as skipped.
175
176 ## Output formats
177
178 By default, µTest uses an output similar to Mocha:
179
180 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
181 $ ./test-suite
182
183 A test suite
184 is made of at least one spec
185 ✓ a to be true
186 ✓ a not to be false
187
188 2 passing (80.0 µs)
189
190 can contain multiple specs
191 ✓ get_greeting() to return all parts of a greeting
192
193 1 passing (60.0 µs)
194
195 can have specs that can be skipped
196 - an answer to the ultimate question of life, the universe and everything
197
198 0 passing (34.0 µs)
199 1 skipped
200
201 Total
202 3 passing (202.0 µs)
203 1 skipped
204 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
205
206 Additionally, µTest supports [TAP](https://testanything.org/)—Test Anything
207 Protocol. If you have a TAP harness, like [prove(1)](https://linux.die.net/man/1/prove),
208 you can use the `MUTEST_OUTPUT` environment variable set to `tap` in order to
209 get a TAP output:
210
211 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
212 $ MUTEST_OUTPUT=tap ./test-suite
213 # A test suite
214 # is made of at least one spec
215 ok 1 - a to be true
216 ok 2 - a not to be false
217 # can contain multiple specs
218 ok 3 - get_greeting() to return all parts of a greeting
219 # can have specs that can be skipped
220 ok 4 - an answer to the ultimate question of life, the universe and everything # SKIP: Deep Thought hasn't finished yet
221 1..4
222 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
223
224 ## API Reference
225
226 - [General](./mutest-general.md.html)
227 - [Matchers](./mutest-matchers.md.html)
228 - [Value wrappers](./mutest-wrappers.md.html)
229 - [Hooks](./mutest-hooks.md.html)
230
231 ## Copyright and license
232
233 Copyright 2019 Emmanuele Bassi
234
235 µTest and this documentation are released under the terms of the
236 [MIT](https://opensource.org/licenses/MIT) license.
237
238 Permission is hereby granted, free of charge, to any person obtaining a copy
239 of this software and associated documentation files (the "Software"), to deal
240 in the Software without restriction, including without limitation the rights
241 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
242 copies of the Software, and to permit persons to whom the Software is
243 furnished to do so, subject to the following conditions:
244
245 The above copyright notice and this permission notice shall be included in
246 all copies or substantial portions of the Software.
247
248 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
249 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
250 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
251 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
252 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
253 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
254 THE SOFTWARE.
255
256 <style class="fallback">body{visibility:hidden}</style><script>markdeepOptions={tocStyle:'medium'};</script>
257 <!-- Markdeep: --><script src="markdeep.min.js" charset="utf-8"></script>