Debian Codegraph @

src/vendor/azure-uamqp-c/deps/azure-ctest/doc/ctest_user_manual.md

raw
1 # CTest
2  
3 ## Overview
4
5 `CTest` is a `C` test harness. It provides a test runner and a set of assert macros that can be used to write tests.
6
7 `CTest` is designed to:
8
9 - Only use C for writing tests in order to minimize mixing C and C++ (sometimes the mix is just not desired)
10 - Maximize portability, thus trying to avoid at any costs compiler implementation specific features.
11 Using CTest
12 The following steps are required in order to use CTest:
13 - Include ctest.h in a .c file
14 - Write the tests in the .c file as part of a test suite
15 - Link the test runner in your executable
16 - As part of main (or any other function), execute the test suite
17
18 ## The first test
19
20 The below example shows a simple test written by using CTest:
21
22 ```c
23 #include "CTest.h"
24 #include "SomeUnitUnderTest.h"
25
26 CTEST_BEGIN_TEST_SUITE(SimpleTestSuiteOneTest)
27
28 CTEST_FUNCTION(Test1)
29 {
30 // arrange
31
32 // act
33 int x = SomeFunction();
34
35 // assert
36 CTEST_ASSERT_ARE_EQUAL(int, 42, x);
37 }
38
39 CTEST_END_TEST_SUITE(SimpleTestSuiteOneTest)
40 ```
41
42 In order to run the suite, the main function would contain:
43
44 ```c
45 #include "CTest.h"
46
47 int main(int argc, char* argv[])
48 {
49 CTEST_RUN_TEST_SUITE(SimpleTestSuiteOneTest);
50
51 return 0;
52 }
53 ```
54
55 The results would look like:
56
57 ![](img/ctest_results.png)
58
59 ## Test suites
60
61 One test suite is supported per translation unit.
62
63 The beginning of a test suite is marked by the macro `CTEST_BEGIN_TEST_SUITE(suiteName)`.
64 The end of a test suite is marked by the macro `CTEST_END_TEST_SUITE(suiteName)`.
65
66 To run all the tests in a test suite the following macro can be used:
67
68 ```c
69 CTEST_RUN_TEST_SUITE(suiteName{,failedTestCount});
70 ```
71
72 The execution order of the tests in a test suite is not guaranteed. Tests are executed sequentially.
73
74 The `failedTestCount` argument for `CTEST_RUN_TEST_SUITE` is optional. If specified, the number of failed tests will be summed up in the `failedTestCount` variable, that is passed as argument.
75
76 ## Fixtures
77
78 ### CTEST_SUITE_INITIALIZE
79
80 This special fixture is executed before all the tests in the test suite. All resources allocated in `CTEST_SUITE_INITIALIZE` should be freed in `CTEST_SUITE_CLEANUP`.
81
82 ```c
83 CTEST_SUITE_INITIALIZE()
84 {
85 /* Some init code */
86 }
87 ```
88
89 ### CTEST_SUITE_CLEANUP
90
91 This special fixture is executed after all the tests in the test suite.
92
93 ```c
94 CTEST_SUITE_CLEANUP()
95 {
96 /* Free resources allocated in CTEST_SUITE_INITIALIZE */
97 }
98 ```
99
100 ### CTEST_FUNCTION_INITIALIZE
101
102 This special fixture is executed before calling each test function in the test suite. All resources allocated in `CTEST_FUNCTION_INITIALIZE` should be freed in `CTEST_FUNCTION_CLEANUP`.
103
104 ```c
105 CTEST_FUNCTION_INITIALIZE()
106 {
107 /* Initialize specific things for each test function */
108 }
109 ```
110
111 ### CTEST_FUNCTION_CLEANUP
112
113 This special fixture is executed after each test in the test suite.
114
115 ```c
116 CTEST_FUNCTION_CLEANUP()
117 {
118 /* Free resources allocated in CTEST_FUNCTION_INITIALIZE */
119 }
120 ```
121
122 ## Assert macros
123
124 Assert macros allow asserting various results and failing the tests if the asserted values/expressions fail.
125 By default if no assert macro fails a test, the test is reported as successful.
126
127 The following assert macros are supported by CTEST:
128
129 ### CTEST_ASSERT_FAIL(message);
130
131 This macro fails the test and displays the message argument.
132
133 ### CTEST_ASSERT_ARE_EQUAL(type, expected, actual, [format, …]);
134
135 This macro compares the expected and actual values, assuming they are of type “type” and fails the test if the values are different.
136
137 ```c
138 CTEST_FUNCTION(Assert_Are_Equal_2_Ints_Fails)
139 {
140 // arrange
141
142 // act
143 int x = SomeFunction();
144
145 // assert
146 CTEST_ASSERT_ARE_EQUAL(int, 42, x);
147 }
148 ```
149
150 ### CTEST_ASSERT_ARE_NOT_EQUAL(type, expected, actual, [format, …]);
151
152 This macro compares the expected and actual values, assuming they are of type `type` and fails the test if the values are equal.
153
154 ```c
155 CTEST_FUNCTION(Assert_Are_Not_Equal_2_Ints_Fails)
156 {
157 // arrange
158
159 // act
160 int x = SomeFunction();
161
162 // assert
163 CTEST_ASSERT_ARE_NOT_EQUAL(int, 0, x);
164 }
165 ```
166
167 When using the `[format, …]` optional arguments to specify an assert message:
168
169 ```c
170 CTEST_FUNCTION(Assert_Are_Not_Equal_2_Ints_Fails)
171 {
172 // arrange
173
174 // act
175 int x = SomeFunction();
176
177 // assert
178 CTEST_ASSERT_ARE_NOT_EQUAL(int, 0, x, "{ Message with int: %d }", 42);
179 }
180 ```
181
182 ### CTEST_ASSERT_IS_NULL(value, [format, …]);
183
184 This macro fails the test if the value argument is not NULL.
185
186 ```c
187 CTEST_FUNCTION(Assert_Is_NULL)
188 {
189 // arrange
190
191 // act
192 void* x = SomeFunction();
193
194 // assert
195 CTEST_ASSERT_IS_NULL(x);
196 }
197 ```
198
199 ### CTEST_ASSERT_IS_NOT_NULL(value, [format, …]);
200
201 This macro fails the test if the value argument is NULL.
202
203 ```c
204 CTEST_FUNCTION(Assert_Is_Not_NULL)
205 {
206 // arrange
207
208 // act
209 void* x = SomeFunction();
210
211 // assert
212 CTEST_ASSERT_IS_NOT_NULL(x);
213 }
214 ```
215
216 ### CTEST_ASSERT_IS_TRUE(expression, [format, …]);
217
218 This macro fails the test if expression evaluates to zero.
219
220 ```c
221 CTEST_FUNCTION(Assert_Is_True)
222 {
223 // arrange
224
225 // act
226 int x = SomeFunction();
227
228 // assert
229 CTEST_ASSERT_IS_TRUE(x == 4);
230 }
231 ```
232
233 ### CTEST_ASSERT_IS_FALSE(value, [format, …]);
234
235 This macro fails the test if expression evaluates to something different than zero.
236
237 ```c
238 CTEST_FUNCTION(Assert_Is_False)
239 {
240 // arrange
241
242 // act
243 int x = SomeFunction();
244
245 // assert
246 CTEST_ASSERT_IS_FALSE(x != 4);
247 }
248 ```
249
250 ## Specialized comparer and string conversion function
251
252 ### CTEST_COMPARE(niceType, type)
253
254 In order to allow comparing of specialized types (i.e. structures, etc.), the `CTEST_COMPARE` macro can be used:
255
256 ```c
257 typedef struct mystruct_tag
258 {
259 unsigned char x;
260 } mystruct;
261
262 CTEST_COMPARE(mystruct_ptr, mystruct*)
263 {
264 return (left->x != right->x)
265 }
266 ```
267
268 A comparer is responsible for comparing 2 values (passed as arguments): left and right.
269
270 `left` and `right`, are of the type “type”. The comparer function should return a value different than zero if the `left` and `right` values are different; otherwise, if the values are equal it should return zero.
271
272 The `niceType` is a `typedef` (cannot contain any invalid characters like space, *, etc).
273
274 ### CTEST_TOSTRING(niceType, type, string, bufferSize, value)
275
276 ```c
277 CTEST_TOSTRING(mystruct_ptr, mystruct*, string, bufferSize, value)
278 {
279 (void)snprintf(string, bufferSize, "{ %d }", (int)value->x);
280 }
281 ```
282
283 The function should print in `dst` the desired representation of value, where `value` is of type `type`, and `dst` is of type `char*`.
284
285 The `niceType` is a `typedef` (cannot contain any invalid characters like space, *, etc).
286
287 ### Out of the box supported types
288
289 The `CTest` harness supports out of the box string formatting and comparers for the following types:
290
291 - `int`
292 - `char`
293 - `short`
294 - `long`
295 - `uint8_t`
296 - `int8_t`
297 - `uint16_t`
298 - `int16_t`
299 - `uint32_t`
300 - `int32_t`
301 - `uint64_t`
302 - `int64_t`
303 - `size_t`
304 - `float`
305 - `double`
306 - `long double`
307 - `char*` (`char_ptr`)
308
309 ### CTEST_DEFINE_ENUM_TYPE
310
311 `CTEST_DEFINE_ENUM_TYPE` can be used with an enum defined by using the macro utils feature `MU_DEFINE_ENUM` in order to generate the needed `_ToString` and `_Compare` functions.
312
313 Example:
314
315 ```c
316 #define TEST_ENUM_VALUES \
317 TEST_VALUE_A, \
318 TEST_VALUE_B
319
320 MU_DEFINE_ENUM(TEST_ENUM, TEST_ENUM_VALUES)
321 MU_DEFINE_ENUM_STRINGS(TEST_ENUM, TEST_ENUM_VALUES)
322 CTEST_DEFINE_ENUM_TYPE(TEST_ENUM, TEST_ENUM_VALUES)
323 ```
324
325 ### CTEST_DEFINE_ENUM_2_TYPE
326
327 `CTEST_DEFINE_ENUM_2_TYPE` can be used with an enum defined by using the macro utils feature `MU_DEFINE_ENUM_2` in order to generate the needed `_ToString` and `_Compare` functions.
328
329 Example:
330
331 ```c
332 #define TEST_ENUM_VALUES \
333 TEST_VALUE_A, 0 \
334 TEST_VALUE_B, 1
335
336 MU_DEFINE_ENUM_2(TEST_ENUM, TEST_ENUM_VALUES)
337 MU_DEFINE_ENUM_STRINGS_2(TEST_ENUM, TEST_ENUM_VALUES)
338 CTEST_DEFINE_ENUM_2_TYPE(TEST_ENUM, TEST_ENUM_VALUES)
339 ```