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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 59 - (hide annotations) (download) (as text)
Sun Oct 30 01:38:20 2005 UTC (18 years, 8 months 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 jds 59 /*
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