CUnit Progammers Guide |
||
|---|---|---|
| Prev | Home | Next |
typedef struct CU_TestRegistry typedef CU_TestRegistry* CU_pTestRegistry CU_ErrorCode CU_initialize_registry(void) void CU_cleanup_registry(void) CU_BOOL CU_registry_initialized(void) CU_pTestRegistry CU_get_registry(void) CU_pTestRegistry CU_set_registry(CU_pTestRegistry pTestRegistry) CU_pTestRegistry CU_create_new_registry(void) void CU_destroy_existing_registry(CU_pTestRegistry* ppRegistry)
typedef struct CU_TestRegistry
{
unsigned int uiNumberOfSuites;
unsigned int uiNumberOfTests;
CU_pSuite pSuite;
} CU_TestRegistry;
typedef CU_TestRegistry* CU_pTestRegistry;
The user normally only needs to initialize the registry before use and
clean up afterwards. However, other functions are provided to
manipulate the registry when necessary.
CU_ErrorCode CU_initialize_registry(void)
The active CUnit test registry must be initialized
before use. The user should call CU_initialize_registry()
before calling any other CUnit functions. Failure to do so will
likely result in a crash. If this function is called more than once,
any existing registry will be cleaned up (i.e. destroyed!) before
creating the new registry. This function may not be called during a
test run (i.e. from a test function or suite initialization/cleanup
function).
An error status code is returned:
| CUE_SUCCESS | initialization was successful. |
| CUE_NOMEMORY | memory allocation failed. |
CU_BOOL CU_registry_initialized(void)
This function can be used to check whether the registry has been initialized. This may be useful if the registry setup is distributed over multiple files that need to make sure the registry is ready for test registration.
void CU_cleanup_registry(void)
When testing is complete, the user should call this
function to clean up and release memory used by the framework. This
should be the last CUnit function called (except for restoring the
test registry using CU_initialize_registry() or
CU_set_registry()).
Failure to call CU_cleanup_registry() will result in
memory leaks. It may be called more than once without creating an
error condition. Note that this function will destroy all
suites (and associated tests) in the registry. Pointers to
registered suites and tests should not be dereferenced after
cleaning up the registry. This function may not be called during a
test run (i.e. from a test function or suite initialization/cleanup
function).
Calling CU_cleanup_registry() will only affect the internal
CU_TestRegistry maintained by the CUnit
framework. Destruction of any other test registries owned by the user
are the responsibility of the user. This can be done explictly by
calling CU_destroy_existing_registry(), or
implicitly by making the registry active using
CU_set_registry() and calling
CU_cleanup_registry() again.
CU_pTestRegistry CU_get_registry(void)
Returns a pointer to the active test registry. The registry is a variable of data type CU_TestRegistry. Direct manipulation of the internal test registry is not recommended - API functions should be used instead. The framework maintains ownership of the registry, so the returned pointer will be invalidated by a call to CU_cleanup_registry() or CU_initialize_registry().
CU_pTestRegistry CU_set_registry(CU_pTestRegistry pTestRegistry)
Replaces the active registry with the specified one. A pointer to the previous registry is returned. It is the caller's responsibility to destroy the old registry. This can be done explictly by calling CU_destroy_existing_registry() for the returned pointer. Alternatively, the registry can be made active using CU_set_registry() and destroyed implicitly when CU_cleanup_registry() is called. Care should be taken not to explicitly destroy a registry that is set as the active one. This can result in multiple frees of the same memory and a likely crash.
CU_pTestRegistry CU_create_new_registry(void)
Creates a new registry and returns a pointer to it. The new registry will not contain any suites or tests. It is the caller's responsibility to destroy the new registry by one of the mechanisms described previously.
void CU_destroy_existing_registry(CU_pTestRegistry* ppRegistry)
Destroys and frees all memory for the specified test
registry, including any registered suites and tests. This function
should not be called for a registry which is set as the active test
registry (e.g. a CU_pTestRegistry pointer retrieved using
CU_get_registry()). This will result in a
multiple free of the same memory when
CU_cleanup_registry() is called. ppRegistry
may not be NULL, but the pointer it points to may be. In
that case, the function has no effect. Note that *ppRegistry will be
set to NULL upon return.
| Deprecated Name | Equivalent New Name |
_TestRegistry |
CU_TestRegistry |
_TestRegistry.uiNumberOfGroups
|
CU_TestRegistry.uiNumberOfSuites
|
_TestRegistry.pGroup
|
CU_TestRegistry.pSuite
|
PTestRegistry |
CU_pTestRegistry |
initialize_registry() |
CU_initialize_registry() |
cleanup_registry() |
CU_cleanup_registry() |
get_registry() |
CU_get_registry() |
set_registry() |
CU_set_registry() |