ucx/test.h@7800811078b8
ucx/test.h
Mon, 12 Aug 2013 14:39:51 +0200
- author
- Mike Becker <universe@uap-core.de>
- date
- Mon, 12 Aug 2013 14:39:51 +0200
- changeset 138
- 7800811078b8
- parent 135
- a0aa1c15f46b
- child 146
- aa376dba1ba8
- permissions
- -rw-r--r--
documented map.h + changed return value of ucx_map_iter_next()
1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 2013 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 * UCX_TEST(function_name)
40 * UCX_TEST_SUBROUTINE(subroutine_name, paramlist) // optional
41 * </pre>
42 *
43 * **** IN SOURCE FILE: ****
44 * <pre>
45 * UCX_TEST_SUBROUTINE(subroutine_name, paramlist) {
46 * // tests with UCX_TEST_ASSERT()
47 * }
48 *
49 * UCX_TEST(function_name) {
50 * // memory allocation and other stuff here
51 * #UCX_TEST_BEGIN
52 * // tests with UCX_TEST_ASSERT() and/or
53 * // calls with UCX_TEST_CALL_SUBROUTINE() here
54 * #UCX_TEST_END
55 * // cleanup of memory here
56 * }
57 * </pre>
58 *
59 * <b>Note:</b> if a test fails, a longjump is performed
60 * back to the #UCX_TEST_BEGIN macro!
61 *
62 * <b>Attention:</b> Do not call own functions within a test, that use
63 * UCX_TEST_ASSERT() macros and are not defined by using UCX_TEST_SUBROUTINE().
64 *
65 *
66 * @author Mike Becker
67 * @author Olaf Wintermann
68 *
69 */
71 #ifndef UCX_TEST_H
72 #define UCX_TEST_H
74 #include "ucx.h"
75 #include <stdio.h>
76 #include <string.h>
77 #include <setjmp.h>
79 #ifdef __cplusplus
80 extern "C" {
81 #endif
83 #ifndef __FUNCTION__
84 /**
85 * Alias for the <code>__func__</code> preprocessor macro.
86 * Some compilers use <code>__func__</code> and others use __FUNC__.
87 * We use __FUNC__ so we define it for those compilers which use
88 * <code>__func__</code>.
89 */
90 #define __FUNCTION__ __func__
91 #endif
93 /** Type for the UcxTestSuite. */
94 typedef struct UcxTestSuite UcxTestSuite;
95 /** Pointer to a test function. */
96 typedef void(*UcxTest)(UcxTestSuite*,FILE*);
97 /** Type for the internal list of test cases. */
98 typedef struct UcxTestList UcxTestList;
100 /** Structure for the internal list of test cases. */
101 struct UcxTestList {
102 /** Test case. */
103 UcxTest test;
104 /** Pointer to the next list element. */
105 UcxTestList *next;
106 };
108 /**
109 * A test suite containing multiple test cases.
110 */
111 struct UcxTestSuite {
112 /** The number of successful tests after the suite has been run. */
113 unsigned int success;
114 /** The number of failed tests after the suite has been run. */
115 unsigned int failure;
116 /**
117 * Internal list of test cases.
118 * Use ucx_test_register() to add tests to this list.
119 */
120 UcxTestList *tests;
121 };
123 /**
124 * Creates a new test suite.
125 * @return a new test suite
126 */
127 UcxTestSuite* ucx_test_suite_new();
128 /**
129 * Destroys a test suite.
130 * @param suite the test suite to destroy
131 */
132 void ucx_test_suite_free(UcxTestSuite* suite);
134 /**
135 * Registers a test function with the specified test suite.
136 *
137 * @param suite the suite, the test function shall be added to
138 * @param test the test function to register
139 * @return <code>EXIT_SUCCESS</code> on success or
140 * <code>EXIT_FAILURE</code> on failure
141 */
142 int ucx_test_register(UcxTestSuite* suite, UcxTest test);
143 /**
144 * Runs a test suite and writes the test log to the specified stream.
145 * @param suite the test suite to run
146 * @param outstream the stream the log shall be written to
147 */
148 void ucx_test_run(UcxTestSuite* suite, FILE* outstream);
150 /**
151 * Macro for a #UcxTest function header.
152 *
153 * Use this macro to declare and/or define an #UcxTest function.
154 *
155 * @param name the name of the test function
156 */
157 #define UCX_TEST(name) void name(UcxTestSuite* _suite_,FILE *_output_)
159 /**
160 * Marks the begin of a test.
161 * <b>Note:</b> Any UCX_TEST_ASSERT() calls must be performed <b>after</b>
162 * #UCX_TEST_BEGIN.
163 *
164 * @see #UCX_TEST_END
165 */
166 #define UCX_TEST_BEGIN fwrite("Running ", 1, 8, _output_);\
167 fwrite(__FUNCTION__, 1, strlen(__FUNCTION__), _output_);\
168 fwrite("... ", 1, 4, _output_);\
169 jmp_buf _env_; \
170 if (!setjmp(_env_)) {
172 /**
173 * Checks a test assertion.
174 * If the assertion is correct, the test carries on. If the assertion is not
175 * correct, the specified message (terminated by a dot and a line break) is
176 * written to the test suites output stream.
177 * @param condition the condition to check
178 * @param message the message that shall be printed out on failure
179 */
180 #define UCX_TEST_ASSERT(condition,message) if (!(condition)) { \
181 fwrite(message".\n", 1, 2+strlen(message), _output_); \
182 _suite_->failure++; \
183 longjmp(_env_, 1);\
184 }
186 /**
187 * Macro for a test subroutine function header.
188 *
189 * Use this to declare and/or define an subroutine that can be called by using
190 * UCX_TEST_CALL_SUBROUTINE().
191 *
192 * @param name the name of the subroutine
193 * @param ... the parameter list
194 *
195 * @see UCX_TEST_CALL_SUBROUTINE()
196 */
197 #define UCX_TEST_SUBROUTINE(name,...) void name(UcxTestSuite* _suite_,\
198 FILE *_output_, jmp_buf _env_, __VA_ARGS__)
200 /**
201 * Macro for calling a test subroutine.
202 *
203 * Subroutines declared with UCX_TEST_SUBROUTINE() can be called by using this
204 * macro.
205 *
206 * <b>Note:</b> You may <b>only</b> call subroutines within a #UCX_TEST_BEGIN-
207 * #UCX_TEST_END-block.
208 *
209 * @param name the name of the subroutine
210 * @param ... the argument list
211 *
212 * @see UCX_TEST_SUBROUTINE()
213 */
214 #define UCX_TEST_CALL_SUBROUTINE(name,...) \
215 name(_suite_,_output_,_env_,__VA_ARGS__);
217 /**
218 * Marks the end of a test.
219 * <b>Note:</b> Any UCX_TEST_ASSERT() calls must be performed <b>before</b>
220 * #UCX_TEST_END.
221 *
222 * @see #UCX_TEST_BEGIN
223 */
224 #define UCX_TEST_END fwrite("success.\n", 1, 9, _output_); _suite_->success++;}
226 #ifdef __cplusplus
227 }
228 #endif
230 #endif /* UCX_TEST_H */
