comparison: ucx/cx/test.h
ucx/cx/test.h
- branch
- newapi
- changeset 253
- 087cc9216f28
equal
deleted
inserted
replaced
| 252:7d176764756d | 253:087cc9216f28 |
|---|---|
| 1 /* | |
| 2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. | |
| 3 * | |
| 4 * Copyright 2017 Mike Becker, Olaf Wintermann All rights reserved. | |
| 5 * | |
| 6 * Redistribution and use in source and binary forms, with or without | |
| 7 * modification, are permitted provided that the following conditions are met: | |
| 8 * | |
| 9 * 1. Redistributions of source code must retain the above copyright | |
| 10 * notice, this list of conditions and the following disclaimer. | |
| 11 * | |
| 12 * 2. Redistributions in binary form must reproduce the above copyright | |
| 13 * notice, this list of conditions and the following disclaimer in the | |
| 14 * documentation and/or other materials provided with the distribution. | |
| 15 * | |
| 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" | |
| 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
| 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
| 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE | |
| 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR | |
| 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF | |
| 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS | |
| 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN | |
| 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) | |
| 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE | |
| 26 * POSSIBILITY OF SUCH DAMAGE. | |
| 27 */ | |
| 28 | |
| 29 /** | |
| 30 * @file: test.h | |
| 31 * | |
| 32 * UCX Test Framework. | |
| 33 * | |
| 34 * Usage of this test framework: | |
| 35 * | |
| 36 * **** IN HEADER FILE: **** | |
| 37 * | |
| 38 * <pre> | |
| 39 * CX_TEST(function_name); | |
| 40 * CX_TEST_SUBROUTINE(subroutine_name, paramlist); // optional | |
| 41 * </pre> | |
| 42 * | |
| 43 * **** IN SOURCE FILE: **** | |
| 44 * <pre> | |
| 45 * CX_TEST_SUBROUTINE(subroutine_name, paramlist) { | |
| 46 * // tests with CX_TEST_ASSERT() | |
| 47 * } | |
| 48 * | |
| 49 * CX_TEST(function_name) { | |
| 50 * // memory allocation and other stuff here | |
| 51 * #CX_TEST_DO { | |
| 52 * // tests with CX_TEST_ASSERT() and/or | |
| 53 * // calls with CX_TEST_CALL_SUBROUTINE() here | |
| 54 * } | |
| 55 * // cleanup of memory here | |
| 56 * } | |
| 57 * </pre> | |
| 58 * | |
| 59 * @attention Do not call own functions within a test, that use | |
| 60 * CX_TEST_ASSERT() macros and are not defined by using CX_TEST_SUBROUTINE(). | |
| 61 * | |
| 62 * @author Mike Becker | |
| 63 * @author Olaf Wintermann | |
| 64 * | |
| 65 */ | |
| 66 | |
| 67 #ifndef UCX_TEST_H | |
| 68 #define UCX_TEST_H | |
| 69 | |
| 70 #include <stdlib.h> | |
| 71 #include <stdio.h> | |
| 72 #include <string.h> | |
| 73 #include <setjmp.h> | |
| 74 | |
| 75 #ifdef __cplusplus | |
| 76 extern "C" { | |
| 77 #endif | |
| 78 | |
| 79 #ifndef __FUNCTION__ | |
| 80 /** | |
| 81 * Alias for the <code>__func__</code> preprocessor macro. | |
| 82 * Some compilers use <code>__func__</code> and others use __FUNCTION__. | |
| 83 * We use __FUNCTION__ so we define it for those compilers which use | |
| 84 * <code>__func__</code>. | |
| 85 */ | |
| 86 #define __FUNCTION__ __func__ | |
| 87 #endif | |
| 88 | |
| 89 // | |
| 90 #if !defined(__clang__) && __GNUC__ > 3 | |
| 91 #pragma GCC diagnostic ignored "-Wclobbered" | |
| 92 #endif | |
| 93 | |
| 94 #ifndef UCX_COMMON_H | |
| 95 /** | |
| 96 * Function pointer compatible with fwrite-like functions. | |
| 97 */ | |
| 98 typedef size_t (*cx_write_func)( | |
| 99 void const *, | |
| 100 size_t, | |
| 101 size_t, | |
| 102 void * | |
| 103 ); | |
| 104 #endif // UCX_COMMON_H | |
| 105 | |
| 106 /** Type for the CxTestSuite. */ | |
| 107 typedef struct CxTestSuite CxTestSuite; | |
| 108 | |
| 109 /** Pointer to a test function. */ | |
| 110 typedef void(*CxTest)(CxTestSuite *, void *, cx_write_func); | |
| 111 | |
| 112 /** Type for the internal list of test cases. */ | |
| 113 typedef struct CxTestSet CxTestSet; | |
| 114 | |
| 115 /** Structure for the internal list of test cases. */ | |
| 116 struct CxTestSet { | |
| 117 | |
| 118 /** Test case. */ | |
| 119 CxTest test; | |
| 120 | |
| 121 /** Pointer to the next list element. */ | |
| 122 CxTestSet *next; | |
| 123 }; | |
| 124 | |
| 125 /** | |
| 126 * A test suite containing multiple test cases. | |
| 127 */ | |
| 128 struct CxTestSuite { | |
| 129 | |
| 130 /** The number of successful tests after the suite has been run. */ | |
| 131 unsigned int success; | |
| 132 | |
| 133 /** The number of failed tests after the suite has been run. */ | |
| 134 unsigned int failure; | |
| 135 | |
| 136 /** The optional name of this test suite. */ | |
| 137 char const *name; | |
| 138 | |
| 139 /** | |
| 140 * Internal list of test cases. | |
| 141 * Use cx_test_register() to add tests to this list. | |
| 142 */ | |
| 143 CxTestSet *tests; | |
| 144 }; | |
| 145 | |
| 146 /** | |
| 147 * Creates a new test suite. | |
| 148 * @param name optional name of the suite | |
| 149 * @return a new test suite | |
| 150 */ | |
| 151 static inline CxTestSuite* cx_test_suite_new(char const *name) { | |
| 152 CxTestSuite* suite = (CxTestSuite*) malloc(sizeof(CxTestSuite)); | |
| 153 if (suite != NULL) { | |
| 154 suite->name = name; | |
| 155 suite->success = 0; | |
| 156 suite->failure = 0; | |
| 157 suite->tests = NULL; | |
| 158 } | |
| 159 | |
| 160 return suite; | |
| 161 } | |
| 162 | |
| 163 /** | |
| 164 * Destroys a test suite. | |
| 165 * @param suite the test suite to destroy | |
| 166 */ | |
| 167 static inline void cx_test_suite_free(CxTestSuite* suite) { | |
| 168 CxTestSet *l = suite->tests; | |
| 169 while (l != NULL) { | |
| 170 CxTestSet *e = l; | |
| 171 l = l->next; | |
| 172 free(e); | |
| 173 } | |
| 174 free(suite); | |
| 175 } | |
| 176 | |
| 177 /** | |
| 178 * Registers a test function with the specified test suite. | |
| 179 * | |
| 180 * @param suite the suite, the test function shall be added to | |
| 181 * @param test the test function to register | |
| 182 * @return zero on success or non-zero on failure | |
| 183 */ | |
| 184 static inline int cx_test_register(CxTestSuite* suite, CxTest test) { | |
| 185 CxTestSet *t = (CxTestSet*) malloc(sizeof(CxTestSet)); | |
| 186 if (t) { | |
| 187 t->test = test; | |
| 188 t->next = NULL; | |
| 189 if (suite->tests == NULL) { | |
| 190 suite->tests = t; | |
| 191 } else { | |
| 192 CxTestSet *last = suite->tests; | |
| 193 while (last->next) { | |
| 194 last = last->next; | |
| 195 } | |
| 196 last->next = t; | |
| 197 } | |
| 198 return 0; | |
| 199 } else { | |
| 200 return 1; | |
| 201 } | |
| 202 } | |
| 203 | |
| 204 /** | |
| 205 * Runs a test suite and writes the test log to the specified stream. | |
| 206 * @param suite the test suite to run | |
| 207 * @param out_target the target buffer or file to write the output to | |
| 208 * @param out_writer the write function writing to \p out_target | |
| 209 */ | |
| 210 static inline void cx_test_run(CxTestSuite *suite, | |
| 211 void *out_target, cx_write_func out_writer) { | |
| 212 if (suite->name == NULL) { | |
| 213 out_writer("*** Test Suite ***\n", 1, 19, out_target); | |
| 214 } else { | |
| 215 out_writer("*** Test Suite : ", 1, 17, out_target); | |
| 216 out_writer(suite->name, 1, strlen(suite->name), out_target); | |
| 217 out_writer(" ***\n", 1, 5, out_target); | |
| 218 } | |
| 219 suite->success = 0; | |
| 220 suite->failure = 0; | |
| 221 for (CxTestSet *elem = suite->tests; elem; elem = elem->next) { | |
| 222 elem->test(suite, out_target, out_writer); | |
| 223 } | |
| 224 out_writer("\nAll test completed.\n", 1, 21, out_target); | |
| 225 char total[80]; | |
| 226 int len = snprintf( | |
| 227 total, 80, | |
| 228 " Total: %u\n Success: %u\n Failure: %u\n\n", | |
| 229 suite->success + suite->failure, suite->success, suite->failure | |
| 230 ); | |
| 231 out_writer(total, 1, len, out_target); | |
| 232 } | |
| 233 | |
| 234 /** | |
| 235 * Runs a test suite and writes the test log to the specified FILE stream. | |
| 236 * @param suite the test suite to run | |
| 237 * @param file the target file to write the output to | |
| 238 */ | |
| 239 #define cx_test_run_f(suite, file) cx_test_run(suite, (void*)file, (cx_write_func)fwrite) | |
| 240 | |
| 241 /** | |
| 242 * Runs a test suite and writes the test log to stdout. | |
| 243 * @param suite the test suite to run | |
| 244 */ | |
| 245 #define cx_test_run_stdout(suite) cx_test_run_f(suite, stdout) | |
| 246 | |
| 247 /** | |
| 248 * Macro for a #CxTest function header. | |
| 249 * | |
| 250 * Use this macro to declare and/or define a #CxTest function. | |
| 251 * | |
| 252 * @param name the name of the test function | |
| 253 */ | |
| 254 #define CX_TEST(name) void name(CxTestSuite* _suite_,void *_output_, cx_write_func _writefnc_) | |
| 255 | |
| 256 /** | |
| 257 * Defines the scope of a test. | |
| 258 * @attention Any CX_TEST_ASSERT() calls must be performed in scope of | |
| 259 * #CX_TEST_DO. | |
| 260 */ | |
| 261 #define CX_TEST_DO _writefnc_("Running ", 1, 8, _output_);\ | |
| 262 _writefnc_(__FUNCTION__, 1, strlen(__FUNCTION__), _output_);\ | |
| 263 _writefnc_("... ", 1, 4, _output_);\ | |
| 264 jmp_buf _env_;\ | |
| 265 for (unsigned int _cx_test_loop_ = 0 ;\ | |
| 266 _cx_test_loop_ == 0 && !setjmp(_env_);\ | |
| 267 _writefnc_("success.\n", 1, 9, _output_),\ | |
| 268 _suite_->success++, _cx_test_loop_++) | |
| 269 | |
| 270 /** | |
| 271 * Checks a test assertion. | |
| 272 * If the assertion is correct, the test carries on. If the assertion is not | |
| 273 * correct, the specified message (terminated by a dot and a line break) is | |
| 274 * written to the test suites output stream. | |
| 275 * @param condition the condition to check | |
| 276 * @param message the message that shall be printed out on failure | |
| 277 */ | |
| 278 #define CX_TEST_ASSERTM(condition,message) if (!(condition)) { \ | |
| 279 char const* _assert_msg_ = message; \ | |
| 280 _writefnc_(_assert_msg_, 1, strlen(_assert_msg_), _output_); \ | |
| 281 _writefnc_(".\n", 1, 2, _output_); \ | |
| 282 _suite_->failure++; \ | |
| 283 longjmp(_env_, 1);\ | |
| 284 } (void) 0 | |
| 285 | |
| 286 /** | |
| 287 * Checks a test assertion. | |
| 288 * If the assertion is correct, the test carries on. If the assertion is not | |
| 289 * correct, the specified message (terminated by a dot and a line break) is | |
| 290 * written to the test suites output stream. | |
| 291 * @param condition the condition to check | |
| 292 */ | |
| 293 #define CX_TEST_ASSERT(condition) CX_TEST_ASSERTM(condition, #condition " failed") | |
| 294 | |
| 295 /** | |
| 296 * Macro for a test subroutine function header. | |
| 297 * | |
| 298 * Use this to declare and/or define a subroutine that can be called by using | |
| 299 * CX_TEST_CALL_SUBROUTINE(). | |
| 300 * | |
| 301 * @param name the name of the subroutine | |
| 302 * @param ... the parameter list | |
| 303 * | |
| 304 * @see CX_TEST_CALL_SUBROUTINE() | |
| 305 */ | |
| 306 #define CX_TEST_SUBROUTINE(name,...) void name(CxTestSuite* _suite_,\ | |
| 307 void *_output_, cx_write_func _writefnc_, jmp_buf _env_, __VA_ARGS__) | |
| 308 | |
| 309 /** | |
| 310 * Macro for calling a test subroutine. | |
| 311 * | |
| 312 * Subroutines declared with CX_TEST_SUBROUTINE() can be called by using this | |
| 313 * macro. | |
| 314 * | |
| 315 * @remark You may <b>only</b> call subroutines within a #CX_TEST_DO block. | |
| 316 * | |
| 317 * @param name the name of the subroutine | |
| 318 * @param ... the argument list | |
| 319 * | |
| 320 * @see CX_TEST_SUBROUTINE() | |
| 321 */ | |
| 322 #define CX_TEST_CALL_SUBROUTINE(name,...) \ | |
| 323 name(_suite_,_output_,_writefnc_,_env_,__VA_ARGS__) | |
| 324 | |
| 325 #ifdef __cplusplus | |
| 326 } | |
| 327 #endif | |
| 328 | |
| 329 #endif /* UCX_TEST_H */ | |
| 330 |
