src/ccunit/CCUnitTestCase.h

   1 /* -*- mode: C; -*- */
   2 /* Copyright (C) 2003, 2010, 2013 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  * TestCase module.
  28  */
  29 #ifndef CCUNITTESTCASE_H
  30 #define CCUNITTESTCASE_H
  31
  32 #include <ccunit/CCUnitConfig.h>
  33 #include <ccunit/CCUnitList.h>
  34 #include <ccunit/CCUnitTest.h>
  35 #include <ccunit/CCUnitTestFunc.h>
  36 #include <ccunit/CCUnitTestResult.h>
  37
  38 /**
  39  * @ingroup CCUnitTest
  40  * @defgroup CCUnitTestCase TestCase
  41  * A test case defines the case 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  * CCUnitTestCase* MathTest_newTestCase ()
  73  * {
  74  *   return ccunit_newTestCase ("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  *   CCUnitTestCase* tcase = MathTest_newTestCase ();
 104  *   ccunit_addTestCase (suite, tcase);
 105  *   ccunit_addTestCase (tcase, MathTest_newTestCase_testAdd ());
 106  *   ccunit_addTestCase (tcase, 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 WritingTestCase
 126  */
 127 typedef struct CCUnitTestCase
 128 {
 129   CCUnitTest test;                              /**< super class */
 130   const char* name;                             /**< test case name */
 131   CCUnitTestFunc* setUpBeforeClass;             /**< setUp for a case */
 132   CCUnitTestFunc* tearDownAfterClass;           /**< tearDown for a case */
 133   CCUnitTestFunc* setUp;                        /**< setUp for each tests */
 134   CCUnitTestFunc* tearDown;                     /**< tearDown for each tests */
 135   CCUnitList testFuncs;                         /**< test functions */
 136 } CCUnitTestCase;
 137
 138 /**
 139  * TestCase definition structure
 140  */
 141 typedef struct CCUnitTestCaseDfn
 142 {
 143   CCUnitTestDfn test;                           /**< super class */
 144   const char* name;                             /**< test case name */
 145   CCUnitTestFunc* testFuncs;                    /**< test functions */
 146 } CCUnitTestCaseDfn;
 147
 148 /**
 149  * create new test case.
 150  *
 151  * @param name test case name.
 152  * @return new test case.
 153  * @ingroup WritingTestCase
 154  */
 155 extern CCUnitTestCase* ccunit_newTestCase (const char* name);
 156
 157 /**
 158  * Destructs test case.
 159  * @param testCase deleting case.
 160  * @ingroup WritingTestCase
 161  */
 162 extern inline void ccunit_deleteTestCase (CCUnitTestCase* testCase);
 163
 164 /**
 165  * add test function to test case.
 166  *
 167  * @param testCase test case.
 168  * @param f test function.
 169  * @ingroup WritingTestCase
 170  */
 171 extern void ccunit_addTestFunc (CCUnitTestCase* testCase, CCUnitTestFunc* f);
 172
 173 /**
 174  * add new test func to test case.
 175  *
 176  * @param testCase test case.
 177  * @param name test case name.
 178  * @param desc test case description.
 179  * @param runTest run test function.
 180  * @return new test func
 181  * @ingroup WritingTestCase
 182  */
 183 extern CCUnitTestFunc* ccunit_addNewTestFunc (CCUnitTestCase* testCase,
 184                                               const char* name,
 185                                               const char* desc,
 186                                               void (*runTest)());
 187 #define CCUNIT_ADDNEWTESTFUNC(TESTCASE, FN) ccunit_addNewTestFunc (TESTCASE, #FN, NULL, FN)
 188
 189 /**
 190  * run test cases and collect its results.
 191  * @param testCase test case.
 192  * @return test result.
 193  * @ingroup ExecutingTest
 194  */
 195 extern inline struct CCUnitTestResult* ccunit_runTestCase (CCUnitTestCase* testCase);
 196
 197 /** @} */
 198 #endif