src/ccunit/CCUnitTestFixture.h

   1 /* -*- mode: C; -*- */
   2 /* Copyright (C) 2003, 2010 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 #include <ccunit/CCUnitTestResult.h>
  37
  38 /**
  39  * @ingroup CCUnitTest
  40  * @defgroup CCUnitTestFixture TestFixture
  41  * A test fixture defines the fixture to run multiple tests.
  42  *
  43  * @{
  44  */
  45
  46 /**
  47  * Wraps a test case with setUp and tearDown function.
  48  *
  49  * A TestCase is used to provide a common environment for a set
  50  * of test cases.
  51  *
  52  * To define a test case, do the following:
  53  * - the case is defined by static variables
  54  * - initialize the case state by setUp function
  55  * - clean-up after a test by tearDown function
  56  *
  57  * Each test runs in its own case so there
  58  * can be no side effects among test runs.
  59  * Here is an example:
  60  *
  61  * @code
  62  * static int value1, value2;
  63  *
  64  * void setUp_MathTest ()
  65  * {
  66  *   value1 = 2;
  67  *   value2 = 3;
  68  * }
  69  *
  70  * ...
  71  *
  72  * CCUnitTestFixture* MathTest_newTestFixture ()
  73  * {
  74  *   return ccunit_newTestFixture ("MathTest", setUp_MathTest, NULL);
  75  * }
  76  * @endcode
  77  *
  78  * For each test implement a function which interacts with the
  79  * case. Verify the expected results with assertions specified by
  80  * calling CCUNIT_ASSERT on the expression you want to test:
  81  *
  82  * @code
  83  * void testAdd ()
  84  * {
  85  *   int result = value1 + value2;
  86  *   CCUNIT_ASSERT (result == 5);
  87  * }
  88  *
  89  * ...
  90  *
  91  * void MathTest_newTestCase_testAdd ()
  92  * {
  93  *   return ccunit_newTestCase ("testAdd", "add test", testAdd);
  94  * }
  95  * @endcode
  96  *
  97  * The tests to be run can be collected into a TestSuite.
  98  *
  99  * @code
 100  * CCUintTestSuite* MathTest_suite ()
 101  * {
 102  *   CCUnitTestSuite* suite = ccunit_newTestSuite ("MathTest");
 103  *   CCUnitTestFixture* fixture = MathTest_newTestFixture ();
 104  *   ccunit_addTestFixture (suite, fixture);
 105  *   ccunit_addTestCase (fixture, MathTest_newTestCase_testAdd ());
 106  *   ccunit_addTestCase (fixture, MathTest_newTestCase_testDivZero ())
 107  *   return suite;
 108  * }
 109  * @endcode
 110  *
 111  * Once the functions are defined you can run them. To do this, use a
 112  * TestRunner.
 113  *
 114  * @code
 115  *   CCUnitTestRunner *runner = ccunit_newTestRunner (stdout);
 116  *   CCUnitTestSuite *suite = MathTest_suite ();
 117  *   runner->run (runner, suite);
 118  * @endcode
 119  *
 120  * A command line tool have been created for convenience. It is located
 121  * in src/tools/ccunit_makeSuite.c.
 122  *
 123  * @see CCUnitTestResult, CCUnitTestCase, CCUnitTestSuite, CCUnitMakeSuite,
 124  *
 125  * @ingroup WritingTestFixture
 126  */
 127 typedef struct CCUnitTestFixture
 128 {
 129   CCUnitTest test;                              /**< super class */
 130   const char* name;                             /**< test fixture name */
 131   CCUnitTestFunc* setup_setUp;                  /**< setUp for a fixture */
 132   CCUnitTestFunc* setup_tearDown;               /**< tearDown for a fixture */
 133   CCUnitTestFunc* setUp;                        /**< setUp for each cases */
 134   CCUnitTestFunc* tearDown;                     /**< tearDown for each cases */
 135   CCUnitList testCases;                         /**< test cases */
 136 } CCUnitTestFixture;
 137
 138 /**
 139  * TestFixture definition structure
 140  */
 141 typedef struct CCUnitTestFixtureDfn
 142 {
 143   CCUnitTestDfn test;                           /**< super class */
 144   const char* name;                             /**< test fixture name */
 145   CCUnitTestFunc setup_setUp;                   /**< setUp for a fixture */
 146   CCUnitTestFunc setup_tearDown;                /**< tearDown for a fixture */
 147   CCUnitTestFunc setUp;                         /**< setUp for each cases */
 148   CCUnitTestFunc tearDown;                      /**< tearDown for each cases */
 149   CCUnitTestFunc* testCases;                    /**< test cases */
 150 } CCUnitTestFixtureDfn;
 151
 152 /**
 153  * create new test fixture.
 154  *
 155  * @param name test fixture name.
 156  * @param setUp test case setUp function.
 157  * @param tearDown test case tearDown function.
 158  * @return new test fixture.
 159  * @ingroup WritingTestFixture
 160  */
 161 extern CCUnitTestFixture* ccunit_newTestFixture (const char* name,
 162                                                  CCUnitTestFunc* setUp,
 163                                                  CCUnitTestFunc* tearDown);
 164
 165 /**
 166  * set test fixture setup functions.
 167  *
 168  * @param name test fixture.
 169  * @param setup_setUp test fixture setUp function.
 170  * @param setup_tearDown test fixture tearDown function.
 171  * @ingroup WritingTestFixture
 172  */
 173 extern inline void ccunit_setTestFixtureSetup (CCUnitTestFixture* fixture,
 174                                                CCUnitTestFunc* setup_setUp,
 175                                                CCUnitTestFunc* setup_tearDown);
 176
 177 /**
 178  * add test case to test fixture.
 179  *
 180  * @param fixture test fixture.
 181  * @param testCase test case
 182  * @ingroup WritingTestFixture
 183  */
 184 extern inline void ccunit_addTestCase (CCUnitTestFixture* fixture,
 185                                        CCUnitTestCase* testCase);
 186
 187 /**
 188  * add new test case to test fixture.
 189  *
 190  * @param fixture test fixture.
 191  * @param name test case name.
 192  * @param desc test case description.
 193  * @param runTest run test function.
 194  * @return new test case
 195  * @ingroup WritingTestFixture
 196  */
 197 extern CCUnitTestCase* ccunit_addNewTestCase (CCUnitTestFixture* fixture,
 198                                               const char* name,
 199                                               const char* desc,
 200                                               void (*runTest)());
 201
 202 /**
 203  * run test cases and collect its results.
 204  * @param f test fixture.
 205  * @return test result.
 206  * @ingroup ExecutingTest
 207  */
 208 extern inline struct CCUnitTestResult* ccunit_runTestFixture (CCUnitTestFixture* f);
 209
 210 /** @} */
 211 #endif