README (7058B)
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>