/*
 *  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
  /** 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 suites in the test registry. */
  unsigned int uiNumberOfTests;           /**< Number of tests in the test 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);
CU_EXPORT void         CU_cleanup_registry(void);
CU_EXPORT CU_BOOL      CU_registry_initialized(void);

CU_EXPORT CU_pSuite CU_add_suite(const char* strName, CU_InitializeFunc pInit, CU_CleanupFunc pClean);
CU_EXPORT CU_pTest  CU_add_test(CU_pSuite pSuite, const char* strName, CU_TestFunc pTestFunc);

/** Shortcut macro for adding a test to a suite. */
#define CU_ADD_TEST(suite, test) (CU_add_test(suite, #test, (CU_TestFunc)test))

/*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*/
/*  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.
 *  This data type is provided to assist CUnit users
 *  manage collections of test 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 test 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. */

/** NULL CU_test_info_t to terminate arrays of tests. */
#define CU_TEST_INFO_NULL { NULL, NULL }
/** NULL CU_suite_info_t to terminate arrays of suites. */
#define CU_SUITE_INFO_NULL { NULL, NULL, NULL, NULL }

CU_EXPORT CU_ErrorCode CU_register_suites(CU_SuiteInfo suite_info[]);
CU_EXPORT CU_ErrorCode CU_register_nsuites(int suite_count, ...);

#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);
CU_EXPORT CU_pTestRegistry CU_set_registry(CU_pTestRegistry pTestRegistry);
CU_EXPORT CU_pTestRegistry CU_create_new_registry(void);
CU_EXPORT void             CU_destroy_existing_registry(CU_pTestRegistry* ppRegistry);
CU_EXPORT CU_pSuite        CU_get_suite_by_name(const char* szSuiteName, CU_pTestRegistry pRegistry);
CU_EXPORT CU_pTest         CU_get_test_by_name(const char* szTestName, CU_pSuite pSuite);

#ifdef CUNIT_BUILD_TESTS
void test_cunit_TestDB(void);
#endif

#ifdef __cplusplus
}
#endif
#endif  /*  CUNIT_TESTDB_H_SEEN  */
/** @} */