testdb.h

cunit

/*
 *  CUnit - A Unit testing framework library for C.
 *  Copyright (C) 2001            Anil Kumar
 *  Copyright (C) 2004,2005,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)
 */

/** @file
 *  Management functions for tests, suites, and the test registry (user interface).
 *  Unit testing in CUnit follows the standard 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

/*  Type definition for Initialization/Cleaup/TestFunction */
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. */

/** CUnit test case data type.
 *  CU_Test is a linked list of unit tests.  Each test
 *  has a name and a callable test function, as well as
 *  links to the next and previous tests in the list.  A
 *  test also holds a jmp_buf reference for use in
 *  implementing fatal assertions.
 *  <P>
 *  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()).
 *  <P>
 *  In the current implementation, the name of each CU_Test
 *  in a suite must have a unique name.  There is no
 *  restriction on the test function.  This means that the
 *  same function could, in principle, be called more than
 *  once as long as it is registered with different tests
 *  having distinct names.
 *  @see CU_Suite
 *  @see CU_TestRegistry
 */
typedef struct CU_Test
{
  char*           pName;                  /**< Test name. */
  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. */

/** CUnit suite data type.
 *  CU_Suite is a linked list of CU_Test containers.
 *  Each suite has a name and count of associated unit
 *  tests.  It also holds a pointer 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.
 *  <P>
 *  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()).
 *  <P>
 *  In the current implementation, the name of each CU_Suite
 *  in a test registry must have a unique name.  There is no
 *  restriction on the contained tests.  This means that the
 *  same CU_Test could, in principle, be run more than
 *  once as long as it is registered with different suites
 *  having distinct names.
 *  @see CU_Test
 * @see CU_TestRegistry
 */
typedef struct CU_Suite
{
  char*             pName;                /**< Suite name. */
  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. */

/** 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.
 *  <P>
 *  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 interfaces.
 *  <P>
 *  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.
 *  <P>
 *  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 the
 *  registry 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