/*
* CUnit - A Unit testing framework library for C.
* Copyright (C) 2001 Anil Kumar
* Copyright (C) 2004-2006 Anil Kumar, Jerry St.Clair
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
/*
* Contains all the Type Definitions and functions declarations
* for the CUnit test database maintenance.
*
* Aug 2001 Initial implementation. (AK)
*
* 09/Aug/2001 Added Preprocessor conditionals for the file. (AK)
*
* 24/aug/2001 Made the linked list from SLL to DLL(doubly linked list). (AK)
*
* 31-Aug-2004 Restructured to eliminate global variables error_number,
* g_pTestRegistry; new interface, support for deprecated
* version 1 interface, moved error handling code to
* CUError.[ch], moved test run counts and _TestResult out
* of TestRegistry to TestRun.h. (JDS)
*
* 01-Sep-2004 Added jmp_buf to CU_Test. (JDS)
*
* 05-Sep-2004 Added internal test interface. (JDS)
*
* 15-Apr-2006 Removed constraint that suites/tests be uniquely named.
* Added ability to turn individual tests/suites on or off.
* Moved doxygen comments for public API here to header. (JDS)
*/
/** @file
* Management functions for tests, suites, and the test registry.
* Unit testing in CUnit follows the common structure of unit
* tests aggregated in suites, which are themselves aggregated
* in a test registry. This module provides functions and
* typedef's to support the creation, registration, and manipulation
* of test cases, suites, and the registry.
*/
/** @addtogroup Framework
* @{
*/
#ifndef CUNIT_TESTDB_H_SEEN
#define CUNIT_TESTDB_H_SEEN
#include <setjmp.h> /* jmp_buf */
#include "CUnit.h"
#include "CUError.h"
#ifdef __cplusplus
extern "C" {
#endif
/*=================================================================
* Typedefs and Data Structures
*=================================================================*/
typedef int (*CU_InitializeFunc)(void); /**< Signature for suite initialization function. */
typedef int (*CU_CleanupFunc)(void); /**< Signature for suite cleanup function. */
typedef void (*CU_TestFunc)(void); /**< Signature for a testing function in a test case. */
/*-----------------------------------------------------------------
* CU_Test, CU_pTest
*-----------------------------------------------------------------*/
/** CUnit test case data type.
* CU_Test is a double linked list of unit tests. Each test has
* a name, a callable test function, and a flag for whether the
* test is active and thus executed during a test run. A test
* also holds links to the next and previous tests in the list,
* as well as a jmp_buf reference for use in implementing fatal
* assertions.<br /><br />
*
* Generally, the linked list includes tests which are associated
* with each other in a CU_Suite. As a result, tests are run in
* the order in which they are added to a suite (see CU_add_test()).
* <br /><br />
*
* It is recommended that the name of each CU_Test in a suite have
* a unique name. Otherwise, only the first-registered test having
* a given name will be accessible by that name. There are no
* restrictions on the test function. This means that the same
* function could, in principle, be called more than once from
* different tests.
*
* @see CU_Suite
* @see CU_TestRegistry
*/
typedef struct CU_Test
{
char* pName; /**< Test name. */
CU_BOOL fActive; /**< Flag for whether test is executed during a run. */
CU_TestFunc pTestFunc; /**< Pointer to the test function. */
jmp_buf* pJumpBuf; /**< Jump buffer for setjmp/longjmp test abort mechanism. */
struct CU_Test* pNext; /**< Pointer to the next test in linked list. */
struct CU_Test* pPrev; /**< Pointer to the previous test in linked list. */
} CU_Test;
typedef CU_Test* CU_pTest; /**< Pointer to a CUnit test case. */
/*-----------------------------------------------------------------
* CU_Suite, CU_pSuite
*-----------------------------------------------------------------*/
/** CUnit suite data type.
* CU_Suite is a linked list of CU_Test containers. Each suite has
* a name, a count of registered unit tests, and a flag for whether
* the suite is active during test runs. It also holds pointers to
* optional initialization and cleanup functions. If non-NULL, these
* are called before and after running the suite's tests, respectively.
* In addition, the suite holds a pointer to the head of the linked
* list of associated CU_Test objects. Finally, pointers to the next
* and previous suites in the linked list are maintained.<br /><br />
*
* Generally, the linked list includes suites which are associated with
* each other in a CU_TestRegistry. As a result, suites are run in the
* order in which they are registered (see CU_add_suite()).<br /><br />
*
* It is recommended that name of each CU_Suite in a test registry have
* a unique name. Otherwise, only the first-registered suite having a
* given name will be accessible by name. There are no restrictions on
* the contained tests. This means that the same CU_Test could, in
* principle, be run more than once fron different suites.
*
* @see CU_Test
* @see CU_TestRegistry
*/
typedef struct CU_Suite
{
char* pName; /**< Suite name. */
CU_BOOL fActive; /**< Flag for whether suite is executed during a run. */
CU_pTest pTest; /**< Pointer to the 1st test in the suite. */
CU_InitializeFunc pInitializeFunc; /**< Pointer to the suite initialization function. */
CU_CleanupFunc pCleanupFunc; /**< Pointer to the suite cleanup function. */
unsigned int uiNumberOfTests; /**< Number of tests in the suite. */
struct CU_Suite* pNext; /**< Pointer to the next suite in linked list. */
struct CU_Suite* pPrev; /**< Pointer to the previous suite in linked list. */
} CU_Suite;
typedef CU_Suite* CU_pSuite; /**< Pointer to a CUnit suite. */
/*-----------------------------------------------------------------
* CU_TestRegistry, CU_pTestRegistry
*-----------------------------------------------------------------*/
/** CUnit test registry data type.
* CU_TestRegisty is the repository for suites containing unit tests.
* The test registry maintains a count of the number of CU_Suite
* objects contained in the registry, as well as a count of the total
* number of CU_Test objects associated with those suites. It also
* holds a pointer to the head of the linked list of CU_Suite objects.
* <br /><br />
*
* With this structure, the user will normally add suites implictly to
* the internal test registry using CU_add_suite(), and then add tests
* to each suite using CU_add_test(). Test runs are then initiated
* using one of the appropriate functions in TestRun.c via one of the
* user interfaces.<br /><br />
*
* Automatic creation and destruction of the internal registry and its
* objects is available using CU_initialize_registry() and
* CU_cleanup_registry(), respectively. For internal and testing
* purposes, the internal registry can be retrieved and assigned.
* Functions are also provided for creating and destroying independent
* registries.<br /><br />
*
* Note that earlier versions of CUnit also contained a pointer to a
* linked list of CU_FailureRecord objects (termed _TestResults).
* This has been removed from theregistry and relocated to TestRun.c.
*
* @see CU_Test
* @see CU_Suite
* @see CU_initialize_registry()
* @see CU_cleanup_registry()
* @see CU_get_registry()
* @see CU_set_registry()
* @see CU_create_new_registry()
* @see CU_destroy_existing_registry()
*/
typedef struct CU_TestRegistry
{
#ifdef USE_DEPRECATED_CUNIT_NAMES
/** Union to support v1.1-1 member name. */
union {
unsigned int uiNumberOfSuites; /**< Number of suites in the test registry. */
unsigned int uiNumberOfGroups; /**< Deprecated (version 1). @deprecated Use uiNumberOfSuites. */
};
unsigned int uiNumberOfTests; /**< Number of tests in the test registry. */
/** Union to support v1.1-1 member name. */
union {
CU_pSuite pSuite; /**< Pointer to the 1st suite in the test registry. */
CU_pSuite pGroup; /**< Deprecated (version 1). @deprecated Use pSuite. */
};
#else
unsigned int uiNumberOfSuites; /**< Number of registered suites in the registry. */
unsigned int uiNumberOfTests; /**< Total number of registered tests in the registry. */
CU_pSuite pSuite; /**< Pointer to the 1st suite in the test registry. */
#endif
} CU_TestRegistry;
typedef CU_TestRegistry* CU_pTestRegistry; /**< Pointer to a CUnit test registry. */
/*=================================================================
* Public interface functions
*=================================================================*/
CU_EXPORT
CU_ErrorCode CU_initialize_registry(void);
/**<
* Initializes the framework test registry.
* Any existing registry is freed, including all stored suites
* and associated tests. It is not necessary to explicitly call
* CU_cleanup_registry() before reinitializing the framework.
* The most recent stored test results are also cleared.<br /><br />
*
* <B>This function must not be called during a test run (checked
* by assertion)</B>
*
* @return CUE_NOMEMORY if memory for the new registry cannot
* be allocated, CUE_SUCCESS otherwise.
* @see CU_cleanup_registry
* @see CU_get_registry
* @see CU_set_registry
* @see CU_registry_initialized
*/
CU_EXPORT
void CU_cleanup_registry(void);
/**<
* Clears the test registry.
* The active test registry is freed, including all stored suites
* and associated tests. The most recent stored test results are
* also cleared. After calling this function, CUnit suites cannot
* be added until CU_initialize_registry() or CU_set_registry() is
* called. Further, any pointers to suites or test cases held by
* the user will be invalidated by calling this function.<br /><br />
*
* This function may be called multiple times without generating
* an error condition. However, <B>this function must not be
* called during a test run (checked by assertion)</B></P>.
*
* @see CU_initialize_registry
* @see CU_get_registry
* @see CU_set_registry
*/
CU_EXPORT CU_BOOL CU_registry_initialized(void);
/**<
* Checks whether the test registry has been initialized.
*
* @return CU_TRUE if the registry has been initialized,
* CU_FALSE otherwise.
* @see CU_initialize_registry
* @see CU_cleanup_registry
*/
CU_EXPORT
CU_pSuite CU_add_suite(const char *strName,
CU_InitializeFunc pInit,
CU_CleanupFunc pClean);
/**<
* Creates a new test suite and adds it to the test registry.
* This function creates a new test suite having the specified
* name and initialization/cleanup functions and adds it to the
* test registry. The new suite will be active and able to be
* executed during a test run. The test registry must be
* initialized before calling this function (checked by assertion).
* pInit and pClean may be NULL, in which case no corresponding
* initialization of cleanup function will be called when the suite
* is run. strName may be empty ("") but may not be NULL.<br /><br />
*
* The return value is a pointer to the newly-created suite, or
* NULL if there was a problem with the suite creation or addition.
* An error code is also set for the framework. Note that if the
* name specified for the new suite is a duplicate, the suite will
* be created and added but the error code will be set to CUE_DUP_SUITE.
* The duplicate suite will not be accessible by name.<br /><br />
*
* NOTE - the CU_pSuite pointer returned should NOT BE FREED BY
* THE USER. The suite is freed by the CUnit system when
* CU_cleanup_registry() is called. <b>This function must not
* be called during a test run (checked by assertion)</b>. <br /><br />
*
* CU_add_suite() sets the following error codes:
* - CUE_SUCCESS if no errors occurred.
* - CUE_NOREGISTRY if the registry has not been initialized.
* - CUE_NO_SUITENAME if strName is NULL.
* - CUE_DUP_SUITE if a suite having strName is already registered.
* - CUE_NOMEMORY if a memory allocation failed.
*
* @param strName Name for the new test suite (non-NULL).
* @param pInit Initialization function to call before running suite.
* @param pClean Cleanup function to call after running suite.
* @return A pointer to the newly-created suite (NULL if creation failed)
*/
CU_EXPORT
CU_ErrorCode CU_set_suite_active(CU_pSuite pSuite, CU_BOOL fNewActive);
/**<
* Activates or deactivates a suite.
* Only activated suites can be executed during a test run.
* By default a suite is active upon creation, but can be deactivated
* by passing it along with CU_FALSE to this function. The suite
* can be reactivated by passing it along with CU_TRUE. The current
* value of the active flag is available as pSuite->fActive. If pSuite
* is NULL then error code CUE_NOSUITE is returned.
*
* @param pSuite Pointer to the suite to modify (non-NULL).
* @param fNewActive If CU_TRUE then the suite will be activated;
* if CU_FALSE it will be deactivated.
* @return Returns CUE_NOSUITE if pSuite is NULL, CUE_SUCCESS if all is well.
*/
CU_EXPORT
CU_ErrorCode CU_set_suite_name(CU_pSuite pSuite, const char *strNewName);
/**<
* Modifies the name of a suite.
* This function allows the name associated with a suite to
* be changed. It is not recommended that a suite name be changed,
* nor should it be necessary under most circumstances. However,
* this function is provided for those clients who need to change
* a suite's name. The current value of the suite's name
* is available as pSuite->pName. CUE_SUCCESS is returned if the
* function succeeds in changing the name. CUE_NOSUITE is returned if
* pSuite is NULL, and CUE_NO_SUITENAME if strNewName is NULL.
*
* @param pSuite Pointer to the suite to modify (non-NULL).
* @param strNewName Pointer to string containing new suite name (non-NULL).
* @return Returns CUE_NOSUITE if pSuite is NULL, CUE_NO_SUITENAME if
* strNewName is NULL, and CUE_SUCCESS if all is well.
*/
CU_EXPORT
CU_ErrorCode CU_set_suite_initfunc(CU_pSuite pSuite, CU_InitializeFunc pNewInit);
/**<
* Modifies the initialization function of a suite.
* This function allows the initialization function associated with
* a suite to be changed. This is neither recommended nor should it
* be necessary under most circumstances. However, this function is
* provided for those clients who need to change the function. The
* current value of the function is available as pSuite->pInitializeFunc.
* CUE_SUCCESS is returned if the function succeeds, or CUE_NOSUITE if
* pSuite is NULL. pNewInit may be NULL, which indicates the suite has
* no initialization function.
*
* @param pSuite Pointer to the suite to modify (non-NULL).
* @param pNewInit Pointer to function to use to initialize suite.
* @return Returns CUE_NOSUITE if pSuite is NULL, and CUE_SUCCESS if
* all is well.
*/
CU_EXPORT
CU_ErrorCode CU_set_suite_cleanupfunc(CU_pSuite pSuite, CU_CleanupFunc pNewClean);
/**<
* Modifies the cleanup function of a suite.
* This function allows the cleanup function associated with a suite to
* be changed. This is neither recommended nor should it be necessary
* under most circumstances. However, this function is provided for those
* clients who need to change the function. The current value of the
* function is available as pSuite->pCleanupFunc. CUE_SUCCESS is returned
* if the function succeeds, or CUE_NOSUITE if pSuite is NULL. pNewClean
* may be NULL, which indicates the suite has no cleanup function.
*
* @param pSuite Pointer to the suite to modify (non-NULL).
* @param pNewClean Pointer to function to use to clean up suite.
* @return Returns CUE_NOSUITE if pSuite is NULL, and CUE_SUCCESS if
* all is well.
*/
CU_EXPORT
CU_pSuite CU_get_suite(const char* strName);
/**<
* Retrieves the suite having the specified name.
* Searches the active test registry and returns a pointer to the 1st
* suite found. NULL is returned if no suite having the specified name
* is found. In addition, the framework error state is set to CUE_NOREGISTRY
* if the registry is not initialized or to CUE_NO_SUITENAME if strName is NULL.
* If the return value is NULL and framework error state is CUE_SUCCESS, then
* the search simply failed to find the specified name.
* Use CU_get_suite_at_pos() to retrieve a suite by position rather than name.
*
* @param strName The name of the suite to search for (non-NULL).
* @return Returns a pointer to the suite, or NULL if not found or an error occurred.
* @see CU_get_suite_at_pos()
*/
CU_EXPORT
CU_pSuite CU_get_suite_at_pos(unsigned int pos);
/**<
* Retrieves the suite at the specified position.
* Iterates the active test registry and returns a pointer to the suite at
* position pos. pos is a 1-based index having valid values
* [1 .. CU_get_registry()->uiNumberOfSuites] and corresponds to the order in
* which suites were registered. If pos is invalid or an error occurs, 0 is
* returned. In addition, the framework error state is set to CUE_NOREGISTRY if
* the registry is not initialized, or CUE_SUCCESS if pos was invalid. Use
* CU_get_suite() to retrieve a suite by name rather than position.
*
* @param pos The 1-based position of the suite to fetch.
* @return Returns a pointer to the suite, or 0 if not found or an error occurred.
* @see CU_get_suite()
*/
CU_EXPORT
unsigned int CU_get_suite_pos(CU_pSuite pSuite);
/**<
* Looks up the position of the specified suite.
* The position is a 1-based index of suites in the active test registry which
* corresponds to the order in which suites were registered. If pSuite is not
* found or an error occurs, 0 is returned. In addition, the framework error
* state is set to CUE_NOREGISTRY if the registry is not initialized, or
* CUE_NOSUITE if pSuite is NULL. The returned position may be used to retrieve
* the suite using CU_get_suite_by_pos().
*
* @param pSuite Pointer to the suite to find (non-NULL).
* @return Returns the 1-based position of pSuite in the registry, or NULL if
* not found or an error occurred.
* @see CU_get_suite_by_pos()
* @see CU_get_suite_pos_by_name()
*/
CU_EXPORT
unsigned int CU_get_suite_pos_by_name(const char* strName);
/**<
* Looks up the position of the suite having the specified name.
* The position is a 1-based index of suites in the active test registry which
* corresponds to the order in which suites were registered. If no suite has the
* specified name or an error occurs, 0 is returned. In addition, the framework error
* state is set to CUE_NOREGISTRY if the registry is not initialized, or
* CUE_NO_SUITENAME if strName is NULL. The search ends at the 1st suite found having
* name strName. The returned position may be used to retrieve the suite using
* CU_get_suite_by_pos().
*
* @param strName Name of the suite to find (non-NULL).
* @return Returns the 1-based position of pSuite in the registry, or NULL if
* not found or an error occurred.
* @see CU_get_suite_by_pos()
* @see CU_get_suite_pos_by_name()
*/
CU_EXPORT
CU_pTest CU_add_test(CU_pSuite pSuite, const char* strName, CU_TestFunc pTestFunc);
/**<
* This function creates a new test having the specified name
* and function, and adds it to the specified suite. The new test
* is active and able to be executed during a test run. At present,
* there is no mechanism for creating a test case independent of a
* suite. Neither pSuite, strName, nor pTestFunc may be NULL.
*
* The return value is a pointer to the newly-created test, or
* NULL if there was a problem with the test creation or addition.
* An error code is also set for the framework. Note that if the
* name specified for the new test is a duplicate within pSuite,
* the test will be created and added but the error code will be
* set to CUE_DUP_TEST. The duplicate test will not be accessible
* by name.<br /><br />
*
* NOTE - the CU_pTest pointer returned should NOT BE FREED BY
* THE USER. The test is freed by the CUnit system when
* CU_cleanup_registry() is called. <b>This function must not
* be called during a test run (checked by assertion)</b>. <br /><br />
* CU_add_test() sets the following error codes:
* - CUE_SUCCESS if no errors occurred.
* - CUE_NOREGISTRY if the registry has not been initialized.
* - CUE_NOSUITE if pSuite is NULL.
* - CUE_NO_TESTNAME if strName is NULL.
* - CUE_NOTEST if pTestFunc is NULL.
* - CUE_DUP_TEST if a test having strName is already registered to pSuite.
* - CUE_NOMEMORY if a memory allocation failed.<br /><br />
*
* @param pSuite Test suite to which to add new test (non-NULL).
* @param strName Name for the new test case (non-NULL).
* @param pTest Function to call when running the test (non-NULL).
* @return A pointer to the newly-created test (NULL if creation failed)
*/
CU_EXPORT
CU_ErrorCode CU_set_test_active(CU_pTest pTest, CU_BOOL fNewActive);
/**<
* Activates or deactivates a specific test.
* Only activated tests can be executed during a test run.
* By default a test is active upon creation, but can be deactvated
* by passing it along with CU_FALSE to this function. The test
* can be reactivated by passing it along with CU_TRUE.
* The current value of the active flag is available as pTest->fActive.
* If pTest is NULL then error code CUE_NOTEST is returned. Otherwise
* CUE_SUCCESS is returned.
*
* @param pTest Pointer to the test to modify (non-NULL).
* @param fNewActive If CU_TRUE then test will be activated;
* if CU_FALSE it will be deactivated.
* @return Returns CUE_NOTEST if pTest is NULL, CUE_SUCCESS if all is well.
*/
CU_EXPORT
CU_ErrorCode CU_set_test_name(CU_pTest pTest, const char *strNewName);
/**<
* Modifies the name of a test.
* This function allows the name associated with a test to
* be changed. It is not recommended that a test name be changed,
* nor should it be necessary under most circumstances. However,
* this function is provided for those clients who need to change
* a test's name. The current value of the test's name is
* available as pTest->pName. CUE_SUCCESS is returned if the
* function succeeds in changing the name. CUE_NOTEST is returned if
* pTest is NULL, and CUE_NO_TESTNAME if strNewName is NULL.
*
* @param pTest Pointer to the test to modify (non-NULL).
* @param strNewName Pointer to string containing new test name (non-NULL).
* @return Returns CUE_NOTEST if pTest is NULL, CUE_NO_TESTNAME if
* strNewName is NULL, and CUE_SUCCESS if all is well.
*/
CU_EXPORT
CU_ErrorCode CU_set_test_func(CU_pTest pTest, CU_TestFunc pNewFunc);
/**<
* Modifies the test function of a test.
* This function allows the test function associated with a test to be
* changed. This is neither recommended nor should it be necessary under
* most circumstances. However, this function is provided for those
* clients who need to change the test function. The current value of
* the test function is available as pTest->pTestFunc. CUE_SUCCESS is
* returned if the function succeeds, or CUE_NOTEST if either pTest or
* pNewFunc is NULL.
*
* @param pTest Pointer to the test to modify (non-NULL).
* @param pNewFunc Pointer to function to use for test function (non-NULL).
* @return Returns CUE_NOTEST if pTest or pNewFunc is NULL, and CUE_SUCCESS
* if all is well.
*/
CU_EXPORT
CU_pTest CU_get_test(CU_pSuite pSuite, const char *strName);
/**<
* Retrieves the test having the specified name.
* Searches pSuite and returns a pointer to the 1st test found named strName.
* NULL is returned if no test having the specified name is found in pSuite.
* In addition, the framework error state is set as follows:
* - CUE_NOREGISTRY if the registry is not initialized
* - CUE_NOSUITE if pSuite is NULL
* - CUE_NO_TESTNAME if strName is NULL.
*
* If the return value is NULL and framework error state is CUE_SUCCESS, then
* the search simply failed to find the specified name. Use CU_get_test_at_pos()
* to retrieve a test by position rather than name.
*
* @param pSuite Pointer to the suite to search (non-NULL).
* @param strName The name of the test to search for (non-NULL).
* @return Returns a pointer to the test, or NULL if not found or an error occurred.
* @see CU_get_test_at_pos()
*/
CU_EXPORT
CU_pTest CU_get_test_at_pos(CU_pSuite pSuite, unsigned int pos);
/**<
* Retrieves the test at the specified position in pSuite.
* Iterates the tests registered in pSuite and returns a pointer to the
* test at position pos. pos is a 1-based index having valid values
* [1 .. pSuite->uiNumberOfTests] and corresponds to the order in
* which tests were added to pSuite. If pos is invalid or an error occurs, 0 is
* returned. In addition, the framework error state is set as follows:
* - CUE_NOREGISTRY if the registry is not initialized
* - CUE_NOSUITE if pSuite is NULL
* Use CU_get_test() to retrieve a test by name rather than position.
*
* @param pSuite Pointer to the suite to search (non-NULL).
* @param pos The 1-based position of the test to fetch.
* @return Returns a pointer to the test, or 0 if not found or an error occurred.
* @see CU_get_test()
*/
CU_EXPORT
unsigned int CU_get_test_pos(CU_pSuite pSuite, CU_pTest pTest);
/**<
* Looks up the position of the specified test in pSuite.
* The position is a 1-based index of tests in pSuite which corresponds to the
* order in which tests were added. If pTest is not found or an error occurs,
* 0 is returned. In addition, the framework error state is set as follows:
* - CUE_NOREGISTRY if the registry is not initialized
* - CUE_NOSUITE if pSuite is NULL
* - CUE_NOTEST if pTest is NULL
*
* The returned position may be used to retrieve the test using CU_get_test_by_pos().
*
* @param pSuite Pointer to the suite to search (non-NULL).
* @param pTest Pointer to the test to find (non-NULL).
* @return Returns the 1-based position of pTest in pSuite, or NULL if
* not found or an error occurred.
* @see CU_get_test_by_pos()
* @see CU_get_test_pos_by_name()
*/
CU_EXPORT
unsigned int CU_get_test_pos_by_name(CU_pSuite pSuite, const char *strName);
/**<
* Looks up the position of the test having the specified name in pSuite.
* The position is a 1-based index of tests in pSuite which corresponds to the order
* in which tests were added. If no test has the specified name or an error occurs,
* 0 is returned. In addition, the framework error state is set as follows:
* - CUE_NOREGISTRY if the registry is not initialized
* - CUE_NOSUITE if pSuite is NULL
* - CUE_NO_TESTNAME if strName is NULL
* The search ends at the 1st test found having name strName. The returned position
* may be used to retrieve the suite using CU_get_test_by_pos().
*
* @param pSuite Pointer to the suite to search (non-NULL).
* @param strName Name of the test to find (non-NULL).
* @return Returns the 1-based position of pTest in pSuite, or NULL if
* not found or an error occurred.
* @see CU_get_test_by_pos()
* @see CU_get_test_pos_by_name()
*/
#define CU_ADD_TEST(suite, test) (CU_add_test(suite, #test, (CU_TestFunc)test))
/**< Shortcut macro for adding a test to a suite. */
/*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
/* This section is based conceptually on code
* Copyright (C) 2004 Aurema Pty Ltd.
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* Derived from code contributed by K. Cheung and Aurema Pty Ltd. (thanks!)
* test_case_t, test_group_t, test_suite_t
*/
/**
* Test case parameters structure.
* This data type is provided to assist CUnit users manage collections of
* tests and suites. It is intended to be used to build arrays of test case
* parameters that can be then be referred to in a CU_suite_info_t variable.
*/
typedef struct CU_TestInfo {
char *pName; /**< Test name. */
CU_TestFunc pTestFunc; /**< Test function. */
} CU_TestInfo;
typedef CU_TestInfo* CU_pTestInfo; /**< Pointer to CU_TestInfo type. */
/**
* Suite parameters.
* This data type is provided to assist CUnit users manage collections of
* tests and suites. It is intended to be used to build arrays of suite
* parameters that can be passed to a bulk registration function such as
* CU_register_suite() or CU_register_suites().
*/
typedef struct CU_SuiteInfo {
char *pName; /**< Suite name. */
CU_InitializeFunc pInitFunc; /**< Suite initialization function. */
CU_CleanupFunc pCleanupFunc; /**< Suite cleanup function */
CU_TestInfo *pTests; /**< Test case array - must be NULL terminated. */
} CU_SuiteInfo;
typedef CU_SuiteInfo* CU_pSuiteInfo; /**< Pointer to CU_SuiteInfo type. */
#define CU_TEST_INFO_NULL { NULL, NULL }
/**< NULL CU_test_info_t to terminate arrays of tests. */
#define CU_SUITE_INFO_NULL { NULL, NULL, NULL, NULL }
/**< NULL CU_suite_info_t to terminate arrays of suites. */
CU_EXPORT CU_ErrorCode CU_register_suites(CU_SuiteInfo suite_info[]);
/**<
* Registers the suites in a single CU_SuiteInfo array.
* Multiple arrays can be registered using CU_register_nsuites().
*
* @param suite_info NULL-terminated array of CU_SuiteInfo items to register.
* @return A CU_ErrorCode indicating the error status.
* @see CU_register_suites()
*/
CU_EXPORT CU_ErrorCode CU_register_nsuites(int suite_count, ...);
/**<
* Registers multiple suite arrays in CU_SuiteInfo format.
* The function accepts a variable number of suite arrays to be registered.
* The number of arrays is indicated by the value of the 1st argument,
* suite_count. Each suite in each array is registered with the CUnit test
* registry, along with all of the associated tests.
*
* @param suite_count The number of CU_SuiteInfo* arguments to follow.
* @param ... suite_count number of CU_SuiteInfo* arguments. NULLs are ignored.
* @return A CU_ErrorCode indicating the error status.
* @see CU_register_suites()
*/
#ifdef USE_DEPRECATED_CUNIT_NAMES
typedef CU_TestInfo test_case_t; /**< Deprecated (version 1). @deprecated Use CU_TestInfo. */
typedef CU_SuiteInfo test_group_t; /**< Deprecated (version 1). @deprecated Use CU_SuiteInfo. */
/** Deprecated (version 1). @deprecated Use CU_SuiteInfo and CU_TestInfo. */
typedef struct test_suite {
char *name; /**< Suite name. Currently not used. */
test_group_t *groups; /**< Test groups. This must be a NULL terminated array. */
} test_suite_t;
/** Deprecated (version 1). @deprecated Use CU_TEST_INFO_NULL. */
#define TEST_CASE_NULL { NULL, NULL }
/** Deprecated (version 1). @deprecated Use CU_TEST_GROUP_NULL. */
#define TEST_GROUP_NULL { NULL, NULL, NULL, NULL }
/** Deprecated (version 1). @deprecated Use CU_register_suites(). */
#define test_group_register(tg) CU_register_suites(tg)
/** Deprecated (version 1). @deprecated Use CU_SuiteInfo and CU_register_suites(). */
CU_EXPORT int test_suite_register(test_suite_t *ts)
{
test_group_t *tg;
int error;
for (tg = ts->groups; tg->pName; tg++)
if ((error = CU_register_suites(tg)) != CUE_SUCCESS)
return error;
return CUE_SUCCESS;
}
#endif /* USE_DEPRECATED_CUNIT_NAMES */
/*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
#ifdef USE_DEPRECATED_CUNIT_NAMES
typedef CU_InitializeFunc InitializeFunc; /**< Deprecated (version 1). @deprecated Use CU_InitializeFunc. */
typedef CU_CleanupFunc CleanupFunc; /**< Deprecated (version 1). @deprecated Use CU_CleanupFunc. */
typedef CU_TestFunc TestFunc; /**< Deprecated (version 1). @deprecated Use CU_TestFunc. */
typedef CU_Test _TestCase; /**< Deprecated (version 1). @deprecated Use CU_Test. */
typedef CU_pTest PTestCase; /**< Deprecated (version 1). @deprecated Use CU_pTest. */
typedef CU_Suite _TestGroup; /**< Deprecated (version 1). @deprecated Use CU_Suite. */
typedef CU_pSuite PTestGroup; /**< Deprecated (version 1). @deprecated Use CU_pSuite. */
typedef CU_TestRegistry _TestRegistry; /**< Deprecated (version 1). @deprecated Use CU_TestRegistry. */
typedef CU_pTestRegistry PTestRegistry; /**< Deprecated (version 1). @deprecated Use CU_pTestRegistry. */
/* Public interface functions */
/** Deprecated (version 1). @deprecated Use CU_initialize_registry(). */
#define initialize_registry() CU_initialize_registry()
/** Deprecated (version 1). @deprecated Use CU_cleanup_registry(). */
#define cleanup_registry() CU_cleanup_registry()
/** Deprecated (version 1). @deprecated Use CU_add_suite(). */
#define add_test_group(name, init, clean) CU_add_suite(name, init, clean)
/** Deprecated (version 1). @deprecated Use CU_add_test(). */
#define add_test_case(group, name, test) CU_add_test(group, name, test)
/* private internal CUnit testing functions */
/** Deprecated (version 1). @deprecated Use CU_get_registry(). */
#define get_registry() CU_get_registry()
/** Deprecated (version 1). @deprecated Use CU_set_registry(). */
#define set_registry(reg) CU_set_registry((reg))
/** Deprecated (version 1). @deprecated Use CU_get_suite_by_name(). */
#define get_group_by_name(group, reg) CU_get_suite_by_name(group, reg)
/** Deprecated (version 1). @deprecated Use CU_get_test_by_name(). */
#define get_test_by_name(test, group) CU_get_test_by_name(test, group)
/** Deprecated (version 1). @deprecated Use ADD_TEST_TO_SUITE. */
#define ADD_TEST_TO_GROUP(group, test) (CU_add_test(group, #test, (CU_TestFunc)test))
#endif /* USE_DEPRECATED_CUNIT_NAMES */
/*=================================================================
* Internal CUnit system functions.
* Should not be routinely called by users.
*=================================================================*/
CU_EXPORT CU_pTestRegistry CU_get_registry(void);
/**<
* Retrieves a pointer to the current test registry.
* Returns NULL if the registry has not been initialized using
* CU_initialize_registry(). Directly accessing the registry
* should not be necessary for most users. This function is
* provided primarily for internal and testing purposes.
*
* @return A pointer to the current registry (NULL if uninitialized).
* @see CU_initialize_registry
* @see CU_set_registry
*/
CU_EXPORT CU_pTestRegistry CU_set_registry(CU_pTestRegistry pTestRegistry);
/**<
* Sets the registry to an existing CU_pTestRegistry instance.
* A pointer to the original registry is returned. Note that the
* original registry is not freed, and it becomes the caller's
* responsibility to do so. Directly accessing the registry
* should not be necessary for most users. This function is
* provided primarily for internal and testing purposes.<br /><br />
*
* <B>This function must not be called during a test run (checked
* by assertion)</B>.
*
* @return A pointer to the original registry that was replaced.
* @see CU_initialize_registry
* @see CU_cleanup_registry
* @see CU_get_registry
*/
CU_EXPORT CU_pTestRegistry CU_create_new_registry(void);
/**<
* Creates and initializes a new test registry.
* Returns a pointer to a new, initialized registry (NULL if memory could
* not be allocated). It is the caller's responsibility to destroy and free
* the new registry (unless it is made the active test registry using
* CU_set_registry()).
*/
CU_EXPORT
void CU_destroy_existing_registry(CU_pTestRegistry* ppRegistry);
/**<
* Destroys and frees all memory for an existing test registry.
* The active test registry is destroyed by the CUnit system in
* CU_cleanup_registry(), so only call this function on registries created
* or held independently of the internal CUnit system.<br /><br />
*
* Once a registry is made the active test registry using CU_set_registry(),
* its destruction will be handled by the framework. ppRegistry may not be
* NULL (checked by assertion), but *ppRegistry can be NULL (in which case the
* function has no effect). Note that *ppRegistry will be set to NULL on return.
*
* @param ppRegistry Address of a pointer to the registry to destroy (non-NULL).
*/
CU_EXPORT
CU_pSuite CU_get_suite_by_name(const char *szSuiteName, CU_pTestRegistry pRegistry);
/**<
* Retrieves a pointer to the suite having the specified name.
* Scans the pRegistry and returns a pointer to the first suite located
* having the specified name. Neither szSuiteName nor pRegistry may be
* NULL (checked by assertion). Clients should normally use CU_get_suite()
* instead, which automatically searches the active test registry.
*
* @param szSuiteName The name of the suite to locate (non-NULL).
* @param pRegistry The registry to scan (non-NULL).
* @return Pointer to the first suite having the specified name,
* NULL if not found.
* @see CU_get_suite()
*/
CU_EXPORT
CU_pSuite CU_get_suite_by_index(unsigned int index, CU_pTestRegistry pRegistry);
/**<
* Retrieves a pointer to the suite at the specified (1-based) index.
* Iterates pRegistry and returns a pointer to the suite located at the
* specified index. pRegistry may not be NULL (checked by assertion).
* Clients should normally use CU_get_suite_at_pos() instead, which
* automatically searches the active test registry.
*
* @param index The 1-based index of the suite to find.
* @param pRegistry The registry to scan (non-NULL).
* @return Pointer to the suite at the specified index, or
* NULL if index is invalid.
* @see CU_get_suite_at_pos()
*/
CU_EXPORT
CU_pTest CU_get_test_by_name(const char* szTestName, CU_pSuite pSuite);
/**<
* Retrieves a pointer to the test case in pSuite having the specified name.
* The first test case in pSuite having the specified name is returned, or
* NULL if not found. Neither szSuiteName nor pSuite may be NULL (checked
* by assertion). Clients should normally use CU_get_test() instead.
*
* @param szTestName The name of the test case to locate (non-NULL).
* @param pSuite The suite to scan (non-NULL).
* @return Pointer to the first test case having the specified name,
* NULL if not found.
* @see CU_get_test()
*/
CU_EXPORT
CU_pTest CU_get_test_by_index(unsigned int index, CU_pSuite pSuite);
/**<
* Retrieves a pointer to the test at the specified (1-based) index.
* Iterates pSuite and returns a pointer to the test located at the
* specified index. pSuite may not be NULL (checked by assertion).
* Clients should normally use CU_get_test_at_pos() instead, which
* automatically searches the active test registry.
*
* @param index The 1-based index of the test to find.
* @param pRegistry The registry to scan (non-NULL).
* @return Pointer to the test at the specified index, or
* NULL if index is invalid.
* @see CU_get_test_at_pos()
*/
#ifdef CUNIT_BUILD_TESTS
void test_cunit_TestDB(void);
#endif
#ifdef __cplusplus
}
#endif
#endif /* CUNIT_TESTDB_H_SEEN */
/** @} */
