Add CuTest and test script.

Update ex1-9 with unit tests using CuTest.

1 files changed, 211 insertions, 0 deletions

diff --git a/cutest-1.5/README.txt b/cutest-1.5/README.txt
new file mode 100644
index 0000000..12b9796
--- /dev/null
+++ b/cutest-1.5/README.txt
@@ -0,0 +1,211 @@
+HOW TO USE

+

+You can use CuTest to create unit tests to drive your development

+in the style of Extreme Programming. You can also add unit tests to

+existing code to ensure that it works as you suspect.

+

+Your unit tests are an investment. They let you to change your

+code and add new features confidently without worrying about

+accidentally breaking earlier features.

+

+

+LICENSING

+

+For details on licensing see license.txt.

+

+

+GETTING STARTED

+

+To add unit testing to your C code the only files you need are

+CuTest.c and CuTest.h. 

+

+CuTestTest.c and AllTests.c have been included to provide an

+example of how to write unit tests and then how to aggregate them

+into suites and into a single AllTests.c file. Suites allow you

+to put group tests into logical sets. AllTests.c combines all the

+suites and runs them. 

+

+You should not have to look inside CuTest.c. Looking in

+CuTestTest.c and AllTests.c (for example usage) should be

+sufficient. 

+

+After downloading the sources, run your compiler to create an

+executable called AllTests.exe. For example, if you are using

+Windows with the cl.exe compiler you would type: 

+

+    cl.exe AllTests.c CuTest.c CuTestTest.c

+    AllTests.exe

+

+This will run all the unit tests associated with CuTest and print

+the output on the console. You can replace cl.exe with gcc or

+your favorite compiler in the command above.

+

+

+DETAILED EXAMPLE

+

+Here is a more detailed example. We will work through a simple

+test first exercise. The goal is to create a library of string

+utilities. First, lets write a function that converts a

+null-terminated string to all upper case.

+

+Ensure that CuTest.c and CuTest.h are accessible from your C

+project. Next, create a file called StrUtil.c with these

+contents:

+

+    #include "CuTest.h"

+    

+    char* StrToUpper(char* str) {

+        return str;

+    }

+    

+    void TestStrToUpper(CuTest *tc) {

+        char* input = strdup("hello world");

+        char* actual = StrToUpper(input);

+        char* expected = "HELLO WORLD";

+        CuAssertStrEquals(tc, expected, actual);

+    }

+   

+    CuSuite* StrUtilGetSuite() {

+        CuSuite* suite = CuSuiteNew();

+        SUITE_ADD_TEST(suite, TestStrToUpper);

+        return suite;

+    }

+    

+Create another file called AllTests.c with these contents:

+

+    #include "CuTest.h"

+    

+    CuSuite* StrUtilGetSuite();

+    

+    void RunAllTests(void) {

+        CuString *output = CuStringNew();

+        CuSuite* suite = CuSuiteNew();

+        

+        CuSuiteAddSuite(suite, StrUtilGetSuite());

+    

+        CuSuiteRun(suite);

+        CuSuiteSummary(suite, output);

+        CuSuiteDetails(suite, output);

+        printf("%s\n", output->buffer);

+    }

+    

+    int main(void) {

+        RunAllTests();

+    }

+

+Then type this on the command line:

+

+    gcc AllTests.c CuTest.c StrUtil.c

+

+to compile. You can replace gcc with your favorite compiler.

+CuTest should be portable enough to handle all Windows and Unix

+compilers. Then to run the tests type:

+

+    a.out

+

+This will print an error because we haven't implemented the

+StrToUpper function correctly. We are just returning the string

+without changing it to upper case. 

+

+    char* StrToUpper(char* str) {

+        return str;

+    }

+

+Rewrite this as follows:

+

+    char* StrToUpper(char* str) {

+        char* p;

+        for (p = str ; *p ; ++p) *p = toupper(*p);

+        return str;

+    }

+

+Recompile and run the tests again. The test should pass this

+time.

+

+

+WHAT TO DO NEXT

+

+At this point you might want to write more tests for the

+StrToUpper function. Here are some ideas:

+

+TestStrToUpper_EmptyString :  pass in ""

+TestStrToUpper_UpperCase   :  pass in "HELLO WORLD"

+TestStrToUpper_MixedCase   :  pass in "HELLO world"

+TestStrToUpper_Numbers     :  pass in "1234 hello"

+

+As you write each one of these tests add it to StrUtilGetSuite

+function. If you don't the tests won't be run. Later as you write

+other functions and write tests for them be sure to include those

+in StrUtilGetSuite also. The StrUtilGetSuite function should

+include all the tests in StrUtil.c

+

+Over time you will create another file called FunkyStuff.c

+containing other functions unrelated to StrUtil. Follow the same

+pattern. Create a FunkyStuffGetSuite function in FunkyStuff.c.

+And add FunkyStuffGetSuite to AllTests.c.

+

+The framework is designed in the way it is so that it is easy to

+organize a lot of tests.

+

+THE BIG PICTURE

+

+Each individual test corresponds to a CuTest. These are grouped

+to form a CuSuite. CuSuites can hold CuTests or other CuSuites.

+AllTests.c collects all the CuSuites in the program into a single

+CuSuite which it then runs as a single CuSuite.

+

+The project is open source so feel free to take a peek under the

+hood at the CuTest.c file to see how it works. CuTestTest.c

+contains tests for CuTest.c. So CuTest tests itself.

+

+Since AllTests.c has a main() you will need to exclude this when

+you are building your product. Here is a nicer way to do this if

+you want to avoid messing with multiple builds. Remove the main()

+in AllTests.c. Note that it just calls RunAllTests(). Instead

+we'll call this directly from the main program.

+

+Now in the main() of the actual program check to see if the

+command line option "--test" was passed. If it was then I call

+RunAllTests() from AllTests.c. Otherwise run the real program.

+

+Shipping the tests with the code can be useful. If you customers

+complain about a problem you can ask them to run the unit tests

+and send you the output. This can help you to quickly isolate the

+piece of your system that is malfunctioning in the customer's

+environment. 

+

+CuTest offers a rich set of CuAssert functions. Here is a list:

+

+void CuAssert(CuTest* tc, char* message, int condition);

+void CuAssertTrue(CuTest* tc, int condition);

+void CuAssertStrEquals(CuTest* tc, char* expected, char* actual);

+void CuAssertIntEquals(CuTest* tc, int expected, int actual);

+void CuAssertPtrEquals(CuTest* tc, void* expected, void* actual);

+void CuAssertPtrNotNull(CuTest* tc, void* pointer);

+

+The project is open source and so you can add other more powerful

+asserts to make your tests easier to write and more concise.

+Please feel free to send me changes you make so that I can

+incorporate them into future releases.

+

+If you see any errors in this document please contact me at

+asimjalis@peakprogramming.com.

+

+

+AUTOMATING TEST SUITE GENERATION

+

+make-tests.sh will grep through all the .c files in the current

+directory and generate the code to run all the tests contained in

+them. Using this script you don't have to worry about writing

+AllTests.c or dealing with any of the other suite code.

+

+

+CREDITS

+

+These people have contributed useful code changes to the CuTest project.

+Thanks!

+

+- [02.23.2003] Dave Glowacki <dglo@hyde.ssec.wisc.edu>

+- [04.17.2009] Tobias Lippert <herrmarder@googlemail.com>

+- [11.13.2009] Eli Bendersky <eliben@gmail.com>

+- [12.14.2009] Andrew Brown <abrown@datasci.com>