/[ascend]/trunk/test/CUnit/TestDB.h
ViewVC logotype

Contents of /trunk/test/CUnit/TestDB.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 59 - (show annotations) (download) (as text)
Sun Oct 30 01:38:20 2005 UTC (15 years ago) by jds
File MIME type: text/x-chdr
File size: 17366 byte(s)
- prototype unit test suite based on CUnit added.
- unit tests for base/generic/general and base/generic/utilites added.
- 2nd manual rework of doxygen documentation in general and utilities.
- bug fixes (mostly general & utilities) found during test development.
- added asc_assert prototype to redirect failures to Asc_Panic() and enable decoupling assertions from NDEBUG.
- some modifications of interface & implementation to facilitate testing.
- utilities/ascPrint & utilities/ascMalloc functions now always included in base libs to minimize recompilation when an interface chooses different options.
1 /*
2 * CUnit - A Unit testing framework library for C.
3 * Copyright (C) 2001 Anil Kumar
4 * Copyright (C) 2004, 2005 Anil Kumar, Jerry St.Clair
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the Free Software
18 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 */
20
21 /*
22 * Contains all the Type Definitions and functions declarations
23 * for the CUnit test database maintenance.
24 *
25 * Created By : Anil Kumar on ...(in month of Aug 2001)
26 * Last Modified : 09/Aug/2001
27 * Comment : Added Preprocessor conditionals for the file.
28 * EMail : aksaharan@yahoo.com
29 *
30 * Last Modified : 24/aug/2001 by Anil Kumar
31 * Comment : Made the linked list from SLL to DLL(doubly linked list).
32 * EMail : aksaharan@yahoo.com
33 *
34 * Last Modified : 31-Aug-2004 (JDS)
35 * Comment : Restructured to eliminate global variables error_number, g_pTestRegistry
36 * new interface, support for deprecated version 1 interface,
37 * moved error handling code to CUError.h and CUError.c, moved
38 * test run counts and _TestResult out of TestRegistry to
39 * TestRun.h.
40 * EMail : jds2@users.sourceforge.net
41 *
42 * Last Modified : 1-Sep-2004 (JDS)
43 * Comment : Added jmp_buf to CU_Test.
44 * Email : jds2@users.sourceforge.net
45 *
46 * Modified : 5-Sep-2004 (JDS)
47 * Comment : Added internal test interface.
48 * EMail : jds2@users.sourceforge.net
49 */
50
51 /** @file
52 * Management functions for tests, suites, and the test registry (user interface).
53 * Unit testing in CUnit follows the standard structure of unit
54 * tests aggregated in suites, which are themselves aggregated
55 * in a test registry. This module provides functions and
56 * typedef's to support the creation, registration, and manipulation
57 * of test cases, suites, and the registry.
58 */
59 /** @addtogroup Framework
60 * @{
61 */
62
63 #ifndef CUNIT_TESTDB_H_SEEN
64 #define CUNIT_TESTDB_H_SEEN
65
66 #include <setjmp.h> /* jmp_buf */
67
68 #include "CUnit.h"
69 #include "CUError.h"
70
71 #ifdef __cplusplus
72 extern "C" {
73 #endif
74
75 /* Type definition for Initialization/Cleaup/TestFunction */
76 typedef int (*CU_InitializeFunc)(void); /**< Signature for suite initialization function. */
77 typedef int (*CU_CleanupFunc)(void); /**< Signature for suite cleanup function. */
78 typedef void (*CU_TestFunc)(void); /**< Signature for a testing function in a test case. */
79
80 /** CUnit test case data type.
81 * CU_Test is a linked list of unit tests. Each test
82 * has a name and a callable test function, as well as
83 * links to the next and previous tests in the list. A
84 * test also holds a jmp_buf reference for use in
85 * implementing fatal assertions.
86 * <P>
87 * Generally, the linked list includes tests which are
88 * associated with each other in a CU_Suite. As a result,
89 * tests are run in the order in which they are added to a
90 * suite (see CU_add_test()).
91 * <P>
92 * In the current implementation, the name of each CU_Test
93 * in a suite must have a unique name. There is no
94 * restriction on the test function. This means that the
95 * same function could, in principle, be called more than
96 * once as long as it is registered with different tests
97 * having distinct names.
98 * @see CU_Suite
99 * @see CU_TestRegistry
100 */
101 typedef struct CU_Test
102 {
103 /*@owned@*//*@null@*/
104 char* pName; /**< Test name. */
105 /*@dependent@*/
106 CU_TestFunc pTestFunc; /**< Pointer to the test function. */
107 /*@dependent@*//*@null@*/
108 jmp_buf* pJumpBuf; /**< Jump buffer for setjmp/longjmp test abort mechanism. */
109
110 /*@owned@*//*@null@*/
111 struct CU_Test* pNext; /**< Pointer to the next test in linked list. */
112 /*@dependent@*//*@null@*/
113 struct CU_Test* pPrev; /**< Pointer to the previous test in linked list. */
114
115 } CU_Test;
116 typedef CU_Test* CU_pTest; /**< Pointer to a CUnit test case. */
117
118 /** CUnit suite data type.
119 * CU_Suite is a linked list of CU_Test containers.
120 * Each suite has a name and count of associated unit
121 * tests. It also holds a pointer to optional
122 * initialization and cleanup functions. If non-NULL,
123 * these are called before and after running the suite's
124 * tests, respectively. In addition, the suite holds a
125 * pointer to the head of the linked list of associated
126 * CU_Test objects. Finally, pointers to the next and
127 * previous suites in the linked list are maintained.
128 * <P>
129 * Generally, the linked list includes suites which are
130 * associated with each other in a CU_TestRegistry. As a
131 * result, suites are run in the order in which they are
132 * registered (see CU_add_suite()).
133 * <P>
134 * In the current implementation, the name of each CU_Suite
135 * in a test registry must have a unique name. There is no
136 * restriction on the contained tests. This means that the
137 * same CU_Test could, in principle, be run more than
138 * once as long as it is registered with different suites
139 * having distinct names.
140 * @see CU_Test
141 * @see CU_TestRegistry
142 */
143 typedef struct CU_Suite
144 {
145 /*@owned@*//*@null@*/
146 char* pName; /**< Suite name. */
147 /*@owned@*//*@null@*/
148 CU_pTest pTest; /**< Pointer to the 1st test in the suite. */
149 /*@dependent@*//*@null@*/
150 CU_InitializeFunc pInitializeFunc; /**< Pointer to the suite initialization function. */
151 /*@dependent@*//*@null@*/
152 CU_CleanupFunc pCleanupFunc; /**< Pointer to the suite cleanup function. */
153
154 unsigned int uiNumberOfTests; /**< Number of tests in the suite. */
155 /*@owned@*//*@null@*/
156 struct CU_Suite* pNext; /**< Pointer to the next suite in linked list. */
157 /*@dependent@*//*@null@*/
158 struct CU_Suite* pPrev; /**< Pointer to the previous suite in linked list. */
159
160 } CU_Suite;
161 typedef CU_Suite* CU_pSuite; /**< Pointer to a CUnit suite. */
162
163 /** CUnit test registry data type.
164 * CU_TestRegisty is the repository for suites containing
165 * unit tests. The test registry maintains a count of the
166 * number of CU_Suite objects contained in the registry, as
167 * well as a count of the total number of CU_Test objects
168 * associated with those suites. It also holds a pointer
169 * to the head of the linked list of CU_Suite objects.
170 * <P>
171 * With this structure, the user will normally add suites
172 * implictly to the internal test registry using CU_add_suite(),
173 * and then add tests to each suite using CU_add_test().
174 * Test runs are then initiated using one of the appropriate
175 * functions in TestRun.c via one of the interfaces.
176 * <P>
177 * Automatic creation and destruction of the internal registry
178 * and its objects is available using CU_initialize_registry()
179 * and CU_cleanup_registry(), respectively. For internal and
180 * testing purposes, the internal registry can be retrieved and
181 * assigned. Functions are also provided for creating and
182 * destroying independent registries.
183 * <P>
184 * Note that earlier versions of CUnit also contained a
185 * pointer to a linked list of CU_FailureRecord objects
186 * (termed _TestResults). This has been removed from the
187 * registry and relocated to TestRun.c.
188 * @see CU_Test
189 * @see CU_Suite
190 * @see CU_initialize_registry()
191 * @see CU_cleanup_registry()
192 * @see CU_get_registry()
193 * @see CU_set_registry()
194 * @see CU_create_new_registry()
195 * @see CU_destroy_existing_registry()
196 */
197 typedef struct CU_TestRegistry
198 {
199 #ifdef USE_DEPRECATED_CUNIT_NAMES
200 /** Union to support v1.1-1 member name. */
201 union {
202 unsigned int uiNumberOfSuites; /**< Number of suites in the test registry. */
203 unsigned int uiNumberOfGroups; /**< Deprecated (version 1). @deprecated Use uiNumberOfSuites. */
204 };
205 unsigned int uiNumberOfTests; /**< Number of tests in the test registry. */
206 /** Union to support v1.1-1 member name. */
207 union {
208 CU_pSuite pSuite; /**< Pointer to the 1st suite in the test registry. */
209 CU_pSuite pGroup; /**< Deprecated (version 1). @deprecated Use pSuite. */
210 };
211 #else
212 unsigned int uiNumberOfSuites; /**< Number of suites in the test registry. */
213 unsigned int uiNumberOfTests; /**< Number of tests in the test registry. */
214 /*@owned@*//*@null@*/
215 CU_pSuite pSuite; /**< Pointer to the 1st suite in the test registry. */
216 #endif
217 } CU_TestRegistry;
218 typedef /*@null@*/ CU_TestRegistry* CU_pTestRegistry;
219 /**< Pointer to a CUnit test registry. */
220
221 /* Public interface functions */
222 CU_EXPORT CU_ErrorCode CU_initialize_registry(void);
223 CU_EXPORT void CU_cleanup_registry(void)/*@modifies internalState@*/;
224
225 /*@null@*//*@dependent@*/
226 CU_EXPORT CU_pSuite CU_add_suite(const char* strName, CU_InitializeFunc pInit, CU_CleanupFunc pClean);
227 /*@null@*//*@dependent@*/
228 CU_EXPORT CU_pTest CU_add_test(CU_pSuite pSuite, const char* strName, CU_TestFunc pTestFunc);
229
230 /** Shortcut macro for adding a test to a suite. */
231 #define CU_ADD_TEST(suite, test) (CU_add_test(suite, #test, (CU_TestFunc)test))
232
233 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
234 /* This section is based conceptually on code
235 * Copyright (C) 2004 Aurema Pty Ltd.
236 *
237 * This library is free software; you can redistribute it and/or
238 * modify it under the terms of the GNU Library General Public
239 * License as published by the Free Software Foundation; either
240 * version 2 of the License, or (at your option) any later version.
241 *
242 * This library is distributed in the hope that it will be useful,
243 * but WITHOUT ANY WARRANTY; without even the implied warranty of
244 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
245 * Library General Public License for more details.
246 *
247 * You should have received a copy of the GNU Library General Public
248 * License along with this library; if not, write to the Free Software
249 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
250 *
251 * Derived from code contributed by K. Cheung and Aurema Pty Ltd. (thanks!)
252 * test_case_t, test_group_t, test_suite_t
253 */
254
255 /** Test case parameters.
256 * This data type is provided to assist CUnit users
257 * manage collections of test and suites. It is
258 * intended to be used to build arrays of test case
259 * parameters that can be then be referred to in
260 * a CU_suite_info_t variable.
261 */
262 typedef struct CU_TestInfo {
263 char *pName; /**< Test name. */
264 CU_TestFunc pTestFunc; /**< Test function. */
265 } CU_TestInfo;
266 typedef CU_TestInfo* CU_pTestInfo; /**< Pointer to CU_TestInfo type. */
267
268 /** Suite parameters.
269 * This data type is provided to assist CUnit users
270 * manage collections of test and suites. It is
271 * intended to be used to build arrays of suite
272 * parameters that can be passed to a bulk registration
273 * function such as CU_register_suite() or
274 * CU_register_suites().
275 */
276 typedef struct CU_SuiteInfo {
277 char *pName; /**< Suite name. */
278 CU_InitializeFunc pInitFunc; /**< Suite initialization function. */
279 CU_CleanupFunc pCleanupFunc; /**< Suite cleanup function */
280 CU_TestInfo *pTests; /**< Test case array - must be NULL terminated. */
281 } CU_SuiteInfo;
282 typedef CU_SuiteInfo* CU_pSuiteInfo; /**< Pointer to CU_SuiteInfo type. */
283
284 /** NULL CU_test_info_t to terminate arrays of tests. */
285 #define CU_TEST_INFO_NULL { NULL, NULL }
286 /** NULL CU_suite_info_t to terminate arrays of suites. */
287 #define CU_SUITE_INFO_NULL { NULL, NULL, NULL, NULL }
288
289 CU_EXPORT CU_ErrorCode CU_register_suites(CU_SuiteInfo suite_info[]);
290 CU_EXPORT CU_ErrorCode CU_register_nsuites(int suite_count, ...);
291
292 #ifdef USE_DEPRECATED_CUNIT_NAMES
293 typedef CU_TestInfo test_case_t; /**< Deprecated (version 1). @deprecated Use CU_TestInfo. */
294 typedef CU_SuiteInfo test_group_t; /**< Deprecated (version 1). @deprecated Use CU_SuiteInfo. */
295
296 /** Deprecated (version 1). @deprecated Use CU_SuiteInfo and CU_TestInfo. */
297 typedef struct test_suite {
298 char *name; /**< Suite name. Currently not used. */
299 test_group_t *groups; /**< Test groups. This must be a NULL terminated array. */
300 } test_suite_t;
301
302 /** Deprecated (version 1). @deprecated Use CU_TEST_INFO_NULL. */
303 #define TEST_CASE_NULL { NULL, NULL }
304 /** Deprecated (version 1). @deprecated Use CU_TEST_GROUP_NULL. */
305 #define TEST_GROUP_NULL { NULL, NULL, NULL, NULL }
306
307 /** Deprecated (version 1). @deprecated Use CU_register_suites(). */
308 #define test_group_register(tg) CU_register_suites(tg)
309
310 /** Deprecated (version 1). @deprecated Use CU_SuiteInfo and CU_register_suites(). */
311 CU_EXPORT int test_suite_register(test_suite_t *ts)
312 {
313 test_group_t *tg;
314 int error;
315
316 for (tg = ts->groups; tg->pName; tg++)
317 if ((error = CU_register_suites(tg)) != CUE_SUCCESS)
318 return error;
319
320 return CUE_SUCCESS;
321 }
322 #endif /* USE_DEPRECATED_CUNIT_NAMES */
323 /*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
324
325 #ifdef USE_DEPRECATED_CUNIT_NAMES
326 typedef CU_InitializeFunc InitializeFunc; /**< Deprecated (version 1). @deprecated Use CU_InitializeFunc. */
327 typedef CU_CleanupFunc CleanupFunc; /**< Deprecated (version 1). @deprecated Use CU_CleanupFunc. */
328 typedef CU_TestFunc TestFunc; /**< Deprecated (version 1). @deprecated Use CU_TestFunc. */
329
330 typedef CU_Test _TestCase; /**< Deprecated (version 1). @deprecated Use CU_Test. */
331 typedef CU_pTest PTestCase; /**< Deprecated (version 1). @deprecated Use CU_pTest. */
332
333 typedef CU_Suite _TestGroup; /**< Deprecated (version 1). @deprecated Use CU_Suite. */
334 typedef CU_pSuite PTestGroup; /**< Deprecated (version 1). @deprecated Use CU_pSuite. */
335
336 typedef CU_TestRegistry _TestRegistry; /**< Deprecated (version 1). @deprecated Use CU_TestRegistry. */
337 typedef CU_pTestRegistry PTestRegistry; /**< Deprecated (version 1). @deprecated Use CU_pTestRegistry. */
338
339 /* Public interface functions */
340 /** Deprecated (version 1). @deprecated Use CU_initialize_registry(). */
341 #define initialize_registry() CU_initialize_registry()
342 /** Deprecated (version 1). @deprecated Use CU_cleanup_registry(). */
343 #define cleanup_registry() CU_cleanup_registry()
344 /** Deprecated (version 1). @deprecated Use CU_add_suite(). */
345 #define add_test_group(name, init, clean) CU_add_suite(name, init, clean)
346 /** Deprecated (version 1). @deprecated Use CU_add_test(). */
347 #define add_test_case(group, name, test) CU_add_test(group, name, test)
348
349 /* private internal CUnit testing functions */
350 /** Deprecated (version 1). @deprecated Use CU_get_registry(). */
351 #define get_registry() CU_get_registry()
352 /** Deprecated (version 1). @deprecated Use CU_set_registry(). */
353 #define set_registry(reg) CU_set_registry((reg))
354
355 /** Deprecated (version 1). @deprecated Use CU_get_suite_by_name(). */
356 #define get_group_by_name(group, reg) CU_get_suite_by_name(group, reg)
357 /** Deprecated (version 1). @deprecated Use CU_get_test_by_name(). */
358 #define get_test_by_name(test, group) CU_get_test_by_name(test, group)
359
360 /** Deprecated (version 1). @deprecated Use ADD_TEST_TO_SUITE. */
361 #define ADD_TEST_TO_GROUP(group, test) (CU_add_test(group, #test, (CU_TestFunc)test))
362 #endif /* USE_DEPRECATED_CUNIT_NAMES */
363
364 /* Internal CUnit system functions. Should not be routinely called by users. */
365 /*@null@*//*@dependent@*/
366 CU_EXPORT CU_pTestRegistry CU_get_registry(void) /*@modifies nothing@*/;
367 /*@owned@*/
368 CU_EXPORT CU_pTestRegistry CU_set_registry(/*@owned@*/ CU_pTestRegistry pRegistry);
369 /*@null@*//*@only@*//*@partial@*/
370 CU_EXPORT CU_pTestRegistry CU_create_new_registry(void);
371 CU_EXPORT void CU_destroy_existing_registry(/*@special@*//*@notnull@*/CU_pTestRegistry* ppRegistry)
372 /*@releases *ppRegistry@*/
373 /*@ensures isnull *ppRegistry@*/
374 ;
375 /*@null@*//*@dependent@*/
376 CU_EXPORT CU_pSuite CU_get_suite_by_name(/*@notnull@*/ const char* szSuiteName,
377 /*@notnull@*/ CU_pTestRegistry pRegistry);
378 /*@null@*//*@dependent@*/
379 CU_EXPORT CU_pTest CU_get_test_by_name(/*@notnull@*/ const char* szTestName,
380 /*@notnull@*/ CU_pSuite pSuite);
381
382 #ifdef CUNIT_BUILD_TESTS
383 void test_cunit_TestDB(void);
384 #endif
385
386 #ifdef __cplusplus
387 }
388 #endif
389 #endif /* CUNIT_TESTDB_H_SEEN */
390 /** @} */

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22