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