2006-08-19 Aaron Bockover <abockover@novell.com>

    * test/README: Added quick guide on adding new tests/groups to the
    driver and some examples on how to perform various tests with the driver

svn path=/trunk/mono/; revision=64041

diff --git a/eglib/ChangeLog b/eglib/ChangeLog
index 08eb3b940e88942f47c0b932e48e43cc720ef4ed..06d55db87d828100f3f55066d3b5c64d18df14b2 100644 (file)
--- a/eglib/ChangeLog
+++ b/eglib/ChangeLog
@@ -1,3 +1,8 @@
+2006-08-19  Aaron Bockover  <abockover@novell.com>
+
+       * test/README: Added quick guide on adding new tests/groups to the 
+       driver and some examples on how to perform various tests with the driver
+
 2006-08-18  Aaron Bockover  <abockover@novell.com>
 
        * test/driver.c: Added getopt support and code timing, among other 

diff --git a/eglib/test/README b/eglib/test/README
new file mode 100644 (file)
index 0000000..08c35ba
--- /dev/null
+++ b/eglib/test/README
@@ -0,0 +1,92 @@
+EGlib Unit Testing
+===============================================================================
+
+       1. Writing new tests
+       2. Using the test driver
+
+===============================================================================
+1. Writing new tests
+===============================================================================
+
+Tests are easy to write, but must be grouped in to logical cases. For instance,
+the GPtrArray group has a number of tests that cover the entire GPtrArray
+implementation.
+
+These logical case groups should be in a single C file, and must have
+three elements:
+
+       #include <glib.h>
+       #include "test.h"
+
+       ...
+       <define test implementations>
+       ...
+
+       static Test groupname_tests [] = {
+               {"groupname_test1", groupname_test1},
+               {"groupname_test1", groupname_test2},
+               {NULL, NULL}
+       };
+
+       DEFINE_TEST_GROUP_INIT(groupname_tests_init, groupname_tests)
+
+A test implementation should look like:
+
+       RESULT groupname_test1()
+       {
+               <perform the test>
+
+               if(test_failed) {
+                       return FAILED("reason: %s", "this works like printf");
+               }
+
+               return OK; /* just NULL, but OK is cute */
+       }
+
+Once a test group is written, it needs to be added to the groups table
+in tests.h:
+
+       DEFINE_TEST_GROUP_INIT_H(groupname_tests_init) // same as in impl
+
+       static Group test_groups [] = {
+               ...
+               {"groupname", groupname_tests_init}
+               ...
+       };
+
+===============================================================================
+2. Using the test driver
+===============================================================================
+
+When tests are written, they are rebuilt with make. Two programs will be
+built:
+
+       test-eglib: the test driver and tests linked against eglib
+       test-glib:  the test driver and tests linked against system glib-2.0
+
+Each driver program works exactly the same. Running test-eglib will run 
+the tests against eglib, and test-glib against glib-2.0.
+
+The test driver supports a few options to allow for performance measuring:
+
+       --help          show all options and available test groups
+       --time          time the overall run and report it, even if --quiet is set
+       --quiet         do not print test results, useful for timing
+       --iterations N  run all or specified test groups N times
+
+Run "test-eglib --help" for more details.
+
+Example: run the ptrarray test group 100000 times and only print the time 
+         it took to perform all iterations
+
+       ./test-eglib -tqi 100000 ptrarray
+
+Example: show single iteration of test output for two groups
+       
+       ./test-eglib ptrarray hashtable
+
+Example: show test output of all available groups
+
+       ./test-eglib
+
+