src/ccunit/CCUnitTestFixture.h

   1 /* -*- mode: C; -*- */
   2 /* Copyright (C) 2003 TSUTSUMI Kikuo.
   3    This file is part of the CCUnit Library.
   4
   5    The CCUnit Library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Lesser General Public License
   7    as published by the Free Software Foundation; either version 2.1 of
   8    the License, or (at your option) any later version.
   9
  10    The CCUnit Library is distributed in the hope that it will be
  11    useful, but WITHOUT ANY WARRANTY; without even the implied warranty
  12    of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public
  16    License along with the CCUnit Library; see the file COPYING.LESSER.
  17    If not, write to the Free Software Foundation, Inc., 59 Temple
  18    Place - Suite 330, Boston, MA 02111-1307, USA.
  19 */
  20
  21 /*
  22  * $Id$
  23  */
  24
  25 /**
  26  * @file
  27  * TestFixture module.
  28  */
  29 #ifndef CCUNITTESTFIXTURE_H
  30 #define CCUNITTESTFIXTURE_H
  31
  32 #include <ccunit/CCUnitConfig.h>
  33 #include <ccunit/CCUnitList.h>
  34 #include <ccunit/CCUnitTest.h>
  35 #include <ccunit/CCUnitTestCase.h>
  36
  37 /**
  38  * @ingroup CCUnitTest
  39  * @defgroup CCUnitTestFixture TestFixture
  40  * A test fixture defines the fixture to run multiple tests.
  41  *
  42  * @{
  43  */
  44
  45 /**
  46  * Wraps a test case with setUp and tearDown methods.
  47  *
  48  * @ingroup WritingTestFixture
  49  *
  50  * A TestCase is used to provide a common environment for a set
  51  * of test cases.
  52  *
  53  * To define a test case, do the following:
  54  * - the case is defined by static variables
  55  * - initialize the case state by setUp function
  56  * - clean-up after a test by tearDown function
  57  *
  58  * Each test runs in its own case so there
  59  * can be no side effects among test runs.
  60  * Here is an example:
  61  *
  62  * @code
  63  * static int value1, value2;
  64  *
  65  * void setUp_MathTest ()
  66  * {
  67  *   value1 = 2;
  68  *   value2 = 3;
  69  * }
  70  *
  71  * ...
  72  *
  73  * CCUnitTestFixture* MathTest_newTestFixture ()
  74  * {
  75  *   return ccunit_newTestFixture ("MathTest", setUp_MathTest, NULL);
  76  * }
  77  * @endcode
  78  *
  79  * For each test implement a function which interacts with the
  80  * case. Verify the expected results with assertions specified by
  81  * calling CCUNIT_ASSERT on the expression you want to test:
  82  *
  83  * @code
  84  * void testAdd ()
  85  * {
  86  *   int result = value1 + value2;
  87  *   CCUNIT_ASSERT (result == 5);
  88  * }
  89  *
  90  * ...
  91  *
  92  * void MathTest_newTestCase_testAdd ()
  93  * {
  94  *   return ccunit_newTestCase ("addTest", "add test", addTest);
  95  * }
  96  * @endcode
  97  *
  98  * The tests to be run can be collected into a TestSuite.
  99  *
 100  * @code
 101  * CCUintTestSuite* MathTest_suite ()
 102  * {
 103  *   CCUnitTestSuite* suite = ccunit_newTestSuite ("MathTest");
 104  *   CCUnitTestFixture* fixture = MathTest_newTestFixture ();
 105  *   ccunit_addTestFixture (suite, fixture);
 106  *   ccunit_addTestCase (fixture, MathTest_newTestCase_testAdd ());
 107  *   ccunit_addTestCase (fixture, MathTest_newTestCase_testDivZero ())
 108  *   return suite;
 109  * }
 110  * @endcode
 111  *
 112  * Once the functions are defined you can run them. To do this, use a
 113  * TestRunner.
 114  *
 115  * @code
 116  *   CCUnitTestRunner *runner = ccunit_newTestRunner (stdout);
 117  *   CCUnitTestSuite *suite = MathTest_suite ();
 118  *   runner->run (runner, suite);
 119  * @endcode
 120  *
 121  * A command line tool have been created for convenience. It is located
 122  * in src/tools/ccunit_makeSuite.c.
 123  *
 124  * @see CCUnitTestResult, CCUnitTestCase, CCUnitTestSuite, CCUnitMakeSuite,
 125  */
 126 typedef struct CCUnitTestFixture
 127 {
 128   CCUnitTest test;                              /**< super class */
 129   const char* name;                             /**< test fixture name */
 130   CCUnitList testCases;                         /**< test cases */
 131   void (*setUp) ();                             /**< setUp function */
 132   void (*tearDown) ();                          /**< tearDown function */
 133 } CCUnitTestFixture;
 134
 135 /**
 136  * create new test fixture.
 137  * @ingroup WritingTestFixture
 138  *
 139  * @param name test fixture name.
 140  * @param setUp test fixture setUp function.
 141  * @param tearDown test fixture tearDown function.
 142  * @return new test fixture.
 143  */
 144 extern CCUnitTestFixture* ccunit_newTestFixture (const char* name,
 145                                                  void (*setUp)(),
 146                                                  void (*tearDown)());
 147
 148 /**
 149  * add test case to test fixture.
 150  *
 151  * @param fixture test fixture.
 152  * @param testCase test case
 153  */
 154 extern inline void ccunit_addTestCase (CCUnitTestFixture* fixture,
 155                                        CCUnitTestCase* testCase);
 156
 157 /**
 158  * add new test case to test fixture.
 159  * @ingroup WritingTestFixture
 160  *
 161  * @param fixture test fixture.
 162  * @param name test case name.
 163  * @param desc test case description.
 164  * @param runTest run test function.
 165  * @return new test case
 166  */
 167 extern CCUnitTestCase* ccunit_addNewTestCase (CCUnitTestFixture* fixture,
 168                                               const char* name,
 169                                               const char* desc,
 170                                               void (*runTest)());
 171
 172 /**
 173  * Runs the bare test sequence.
 174  *
 175  * @param testFixture test fixture to run.
 176  * @param runTest test run function.
 177  * @throws _ccunit_runResult_env by longjmp.
 178  */
 179 extern void ccunit_runBare (CCUnitTestFixture* testFixture, void (*runTest)());
 180
 181 /** @} */
 182 #endif