Wed, 27 Dec 2023 14:54:04 +0100
change default make target from 'compile test-compile' to 'check'
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 */
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 */
67 #ifndef UCX_TEST_H
68 #define UCX_TEST_H
70 #include <stdlib.h>
71 #include <stdio.h>
72 #include <string.h>
73 #include <setjmp.h>
75 #ifdef __cplusplus
76 extern "C" {
77 #endif
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
89 #ifndef UCX_COMMON_H
90 /**
91 * Function pointer compatible with fwrite-like functions.
92 */
93 typedef size_t (*cx_write_func)(
94 void const *,
95 size_t,
96 size_t,
97 void *
98 );
99 #endif // UCX_COMMON_H
101 /** Type for the CxTestSuite. */
102 typedef struct CxTestSuite CxTestSuite;
104 /** Pointer to a test function. */
105 typedef void(*CxTest)(CxTestSuite *, void *, cx_write_func);
107 /** Type for the internal list of test cases. */
108 typedef struct CxTestSet CxTestSet;
110 /** Structure for the internal list of test cases. */
111 struct CxTestSet {
113 /** Test case. */
114 CxTest test;
116 /** Pointer to the next list element. */
117 CxTestSet *next;
118 };
120 /**
121 * A test suite containing multiple test cases.
122 */
123 struct CxTestSuite {
125 /** The number of successful tests after the suite has been run. */
126 unsigned int success;
128 /** The number of failed tests after the suite has been run. */
129 unsigned int failure;
131 /** The optional name of this test suite. */
132 char const *name;
134 /**
135 * Internal list of test cases.
136 * Use cx_test_register() to add tests to this list.
137 */
138 CxTestSet *tests;
139 };
141 /**
142 * Creates a new test suite.
143 * @param name optional name of the suite
144 * @return a new test suite
145 */
146 static inline CxTestSuite* cx_test_suite_new(char const *name) {
147 CxTestSuite* suite = (CxTestSuite*) malloc(sizeof(CxTestSuite));
148 if (suite != NULL) {
149 suite->name = name;
150 suite->success = 0;
151 suite->failure = 0;
152 suite->tests = NULL;
153 }
155 return suite;
156 }
158 /**
159 * Destroys a test suite.
160 * @param suite the test suite to destroy
161 */
162 static inline void cx_test_suite_free(CxTestSuite* suite) {
163 CxTestSet *l = suite->tests;
164 while (l != NULL) {
165 CxTestSet *e = l;
166 l = l->next;
167 free(e);
168 }
169 free(suite);
170 }
172 /**
173 * Registers a test function with the specified test suite.
174 *
175 * @param suite the suite, the test function shall be added to
176 * @param test the test function to register
177 * @return zero on success or non-zero on failure
178 */
179 static inline int cx_test_register(CxTestSuite* suite, CxTest test) {
180 CxTestSet *t = (CxTestSet*) malloc(sizeof(CxTestSet));
181 if (t) {
182 t->test = test;
183 t->next = NULL;
184 if (suite->tests == NULL) {
185 suite->tests = t;
186 } else {
187 CxTestSet *last = suite->tests;
188 while (last->next) {
189 last = last->next;
190 }
191 last->next = t;
192 }
193 return 0;
194 } else {
195 return 1;
196 }
197 }
199 /**
200 * Runs a test suite and writes the test log to the specified stream.
201 * @param suite the test suite to run
202 * @param out_target the target buffer or file to write the output to
203 * @param out_writer the write function writing to \p out_target
204 */
205 static inline void cx_test_run(CxTestSuite *suite,
206 void *out_target, cx_write_func out_writer) {
207 if (suite->name == NULL) {
208 out_writer("*** Test Suite ***\n", 1, 19, out_target);
209 } else {
210 out_writer("*** Test Suite : ", 1, 17, out_target);
211 out_writer(suite->name, 1, strlen(suite->name), out_target);
212 out_writer(" ***\n", 1, 5, out_target);
213 }
214 suite->success = 0;
215 suite->failure = 0;
216 for (CxTestSet *elem = suite->tests; elem; elem = elem->next) {
217 elem->test(suite, out_target, out_writer);
218 }
219 out_writer("\nAll test completed.\n", 1, 21, out_target);
220 char total[80];
221 int len = snprintf(
222 total, 80,
223 " Total: %u\n Success: %u\n Failure: %u\n\n",
224 suite->success + suite->failure, suite->success, suite->failure
225 );
226 out_writer(total, 1, len, out_target);
227 }
229 /**
230 * Runs a test suite and writes the test log to the specified FILE stream.
231 * @param suite the test suite to run
232 * @param file the target file to write the output to
233 */
234 #define cx_test_run_f(suite, file) cx_test_run(suite, (void*)file, (cx_write_func)fwrite)
236 /**
237 * Runs a test suite and writes the test log to stdout.
238 * @param suite the test suite to run
239 */
240 #define cx_test_run_stdout(suite) cx_test_run_f(suite, stdout)
242 /**
243 * Macro for a #CxTest function header.
244 *
245 * Use this macro to declare and/or define a #CxTest function.
246 *
247 * @param name the name of the test function
248 */
249 #define CX_TEST(name) void name(CxTestSuite* _suite_,void *_output_, cx_write_func _writefnc_)
251 /**
252 * Defines the scope of a test.
253 * @attention Any CX_TEST_ASSERT() calls must be performed in scope of
254 * #CX_TEST_DO.
255 */
256 #define CX_TEST_DO _writefnc_("Running ", 1, 8, _output_);\
257 _writefnc_(__FUNCTION__, 1, strlen(__FUNCTION__), _output_);\
258 _writefnc_("... ", 1, 4, _output_);\
259 jmp_buf _env_;\
260 for (unsigned int _cx_test_loop_ = 0 ;\
261 _cx_test_loop_ == 0 && !setjmp(_env_);\
262 _writefnc_("success.\n", 1, 9, _output_),\
263 _suite_->success++, _cx_test_loop_++)
265 /**
266 * Checks a test assertion.
267 * If the assertion is correct, the test carries on. If the assertion is not
268 * correct, the specified message (terminated by a dot and a line break) is
269 * written to the test suites output stream.
270 * @param condition the condition to check
271 * @param message the message that shall be printed out on failure
272 */
273 #define CX_TEST_ASSERTM(condition,message) if (!(condition)) { \
274 char const* _assert_msg_ = message; \
275 _writefnc_(_assert_msg_, 1, strlen(_assert_msg_), _output_); \
276 _writefnc_(".\n", 1, 2, _output_); \
277 _suite_->failure++; \
278 longjmp(_env_, 1);\
279 } (void) 0
281 /**
282 * Checks a test assertion.
283 * If the assertion is correct, the test carries on. If the assertion is not
284 * correct, the specified message (terminated by a dot and a line break) is
285 * written to the test suites output stream.
286 * @param condition the condition to check
287 */
288 #define CX_TEST_ASSERT(condition) CX_TEST_ASSERTM(condition, #condition " failed")
290 /**
291 * Macro for a test subroutine function header.
292 *
293 * Use this to declare and/or define a subroutine that can be called by using
294 * CX_TEST_CALL_SUBROUTINE().
295 *
296 * @param name the name of the subroutine
297 * @param ... the parameter list
298 *
299 * @see CX_TEST_CALL_SUBROUTINE()
300 */
301 #define CX_TEST_SUBROUTINE(name,...) void name(CxTestSuite* _suite_,\
302 void *_output_, jmp_buf _env_, __VA_ARGS__)
304 /**
305 * Macro for calling a test subroutine.
306 *
307 * Subroutines declared with CX_TEST_SUBROUTINE() can be called by using this
308 * macro.
309 *
310 * @remark You may <b>only</b> call subroutines within a #CX_TEST_DO block.
311 *
312 * @param name the name of the subroutine
313 * @param ... the argument list
314 *
315 * @see CX_TEST_SUBROUTINE()
316 */
317 #define CX_TEST_CALL_SUBROUTINE(name,...) \
318 name(_suite_,_output_,_writefnc_,_env_,__VA_ARGS__);
320 #ifdef __cplusplus
321 }
322 #endif
324 #endif /* UCX_TEST_H */