build/cutest/README.txt

   1 HOW TO USE
   2
   3 You can use CuTest to create unit tests to drive your development
   4 in the style of Extreme Programming. You can also add unit tests to
   5 existing code to ensure that it works as you suspect.
   6
   7 Your unit tests are an investment. They let you to change your
   8 code and add new features confidently without worrying about
   9 accidentally breaking earlier features.
  10
  11
  12 LICENSING
  13
  14 For details on licensing see license.txt.
  15
  16
  17 GETTING STARTED
  18
  19 To add unit testing to your C code the only files you need are
  20 CuTest.c and CuTest.h.
  21
  22 CuTestTest.c and AllTests.c have been included to provide an
  23 example of how to write unit tests and then how to aggregate them
  24 into suites and into a single AllTests.c file. Suites allow you
  25 to put group tests into logical sets. AllTests.c combines all the
  26 suites and runs them.
  27
  28 You should not have to look inside CuTest.c. Looking in
  29 CuTestTest.c and AllTests.c (for example usage) should be
  30 sufficient.
  31
  32 After downloading the sources, run your compiler to create an
  33 executable called AllTests.exe. For example, if you are using
  34 Windows with the cl.exe compiler you would type:
  35
  36     cl.exe AllTests.c CuTest.c CuTestTest.c
  37     AllTests.exe
  38
  39 This will run all the unit tests associated with CuTest and print
  40 the output on the console. You can replace cl.exe with gcc or
  41 your favorite compiler in the command above.
  42
  43
  44 DETAILED EXAMPLE
  45
  46 Here is a more detailed example. We will work through a simple
  47 test first exercise. The goal is to create a library of string
  48 utilities. First, lets write a function that converts a
  49 null-terminated string to all upper case.
  50
  51 Ensure that CuTest.c and CuTest.h are accessible from your C
  52 project. Next, create a file called StrUtil.c with these
  53 contents:
  54
  55     #include "CuTest.h"
  56
  57     char* StrToUpper(char* str) {
  58         return str;
  59     }
  60
  61     void TestStrToUpper(CuTest *tc) {
  62         char* input = strdup("hello world");
  63         char* actual = StrToUpper(input);
  64         char* expected = "HELLO WORLD";
  65         CuAssertStrEquals(tc, expected, actual);
  66     }
  67
  68     CuSuite* StrUtilGetSuite() {
  69         CuSuite* suite = CuSuiteNew();
  70         SUITE_ADD_TEST(suite, TestStrToUpper);
  71         return suite;
  72     }
  73
  74 Create another file called AllTests.c with these contents:
  75
  76     #include "CuTest.h"
  77
  78     CuSuite* StrUtilGetSuite();
  79
  80     void RunAllTests(void) {
  81         CuString *output = CuStringNew();
  82         CuSuite* suite = CuSuiteNew();
  83
  84         CuSuiteAddSuite(suite, StrUtilGetSuite());
  85
  86         CuSuiteRun(suite);
  87         CuSuiteSummary(suite, output);
  88         CuSuiteDetails(suite, output);
  89         printf("%s\n", output->buffer);
  90     }
  91
  92     int main(void) {
  93         RunAllTests();
  94     }
  95
  96 Then type this on the command line:
  97
  98     gcc AllTests.c CuTest.c StrUtil.c
  99
 100 to compile. You can replace gcc with your favorite compiler.
 101 CuTest should be portable enough to handle all Windows and Unix
 102 compilers. Then to run the tests type:
 103
 104     a.out
 105
 106 This will print an error because we haven't implemented the
 107 StrToUpper function correctly. We are just returning the string
 108 without changing it to upper case.
 109
 110     char* StrToUpper(char* str) {
 111         return str;
 112     }
 113
 114 Rewrite this as follows:
 115
 116     char* StrToUpper(char* str) {
 117         char* p;
 118         for (p = str ; *p ; ++p) *p = toupper(*p);
 119         return str;
 120     }
 121
 122 Recompile and run the tests again. The test should pass this
 123 time.
 124
 125
 126 WHAT TO DO NEXT
 127
 128 At this point you might want to write more tests for the
 129 StrToUpper function. Here are some ideas:
 130
 131 TestStrToUpper_EmptyString :  pass in ""
 132 TestStrToUpper_UpperCase   :  pass in "HELLO WORLD"
 133 TestStrToUpper_MixedCase   :  pass in "HELLO world"
 134 TestStrToUpper_Numbers     :  pass in "1234 hello"
 135
 136 As you write each one of these tests add it to StrUtilGetSuite
 137 function. If you don't the tests won't be run. Later as you write
 138 other functions and write tests for them be sure to include those
 139 in StrUtilGetSuite also. The StrUtilGetSuite function should
 140 include all the tests in StrUtil.c
 141
 142 Over time you will create another file called FunkyStuff.c
 143 containing other functions unrelated to StrUtil. Follow the same
 144 pattern. Create a FunkyStuffGetSuite function in FunkyStuff.c.
 145 And add FunkyStuffGetSuite to AllTests.c.
 146
 147 The framework is designed in the way it is so that it is easy to
 148 organize a lot of tests.
 149
 150 THE BIG PICTURE
 151
 152 Each individual test corresponds to a CuTest. These are grouped
 153 to form a CuSuite. CuSuites can hold CuTests or other CuSuites.
 154 AllTests.c collects all the CuSuites in the program into a single
 155 CuSuite which it then runs as a single CuSuite.
 156
 157 The project is open source so feel free to take a peek under the
 158 hood at the CuTest.c file to see how it works. CuTestTest.c
 159 contains tests for CuTest.c. So CuTest tests itself.
 160
 161 Since AllTests.c has a main() you will need to exclude this when
 162 you are building your product. Here is a nicer way to do this if
 163 you want to avoid messing with multiple builds. Remove the main()
 164 in AllTests.c. Note that it just calls RunAllTests(). Instead
 165 we'll call this directly from the main program.
 166
 167 Now in the main() of the actual program check to see if the
 168 command line option "--test" was passed. If it was then I call
 169 RunAllTests() from AllTests.c. Otherwise run the real program.
 170
 171 Shipping the tests with the code can be useful. If you customers
 172 complain about a problem you can ask them to run the unit tests
 173 and send you the output. This can help you to quickly isolate the
 174 piece of your system that is malfunctioning in the customer's
 175 environment.
 176
 177 CuTest offers a rich set of CuAssert functions. Here is a list:
 178
 179 void CuAssert(CuTest* tc, char* message, int condition);
 180 void CuAssertTrue(CuTest* tc, int condition);
 181 void CuAssertStrEquals(CuTest* tc, char* expected, char* actual);
 182 void CuAssertIntEquals(CuTest* tc, int expected, int actual);
 183 void CuAssertPtrEquals(CuTest* tc, void* expected, void* actual);
 184 void CuAssertPtrNotNull(CuTest* tc, void* pointer);
 185
 186 The project is open source and so you can add other more powerful
 187 asserts to make your tests easier to write and more concise.
 188 Please feel free to send me changes you make so that I can
 189 incorporate them into future releases.
 190
 191 If you see any errors in this document please contact me at
 192 asimjalis@peakprogramming.com.
 193
 194
 195 AUTOMATING TEST SUITE GENERATION
 196
 197 make-tests.sh will grep through all the .c files in the current
 198 directory and generate the code to run all the tests contained in
 199 them. Using this script you don't have to worry about writing
 200 AllTests.c or dealing with any of the other suite code.
 201
 202
 203 CREDITS
 204
 205 These people have contributed useful code changes to the CuTest project.
 206 Thanks!
 207
 208 - [02.23.2003] Dave Glowacki <dglo@hyde.ssec.wisc.edu>
 209 - [04.17.2009] Tobias Lippert <herrmarder@googlemail.com>
 210 - [11.13.2009] Eli Bendersky <eliben@gmail.com>
 211 - [12.14.2009] Andrew Brown <abrown@datasci.com>