eglib/test/README

   1 EGlib Unit Testing
   2 ===============================================================================
   3
   4         1. Writing new tests
   5         2. Using the test driver
   6
   7 ===============================================================================
   8 1. Writing new tests
   9 ===============================================================================
  10
  11 Tests are easy to write, but must be grouped in to logical cases. For instance,
  12 the GPtrArray group has a number of tests that cover the entire GPtrArray
  13 implementation.
  14
  15 These logical case groups should be in a single C file, and must have
  16 three elements:
  17
  18         #include <glib.h>
  19         #include "test.h"
  20
  21         ...
  22         <define test implementations>
  23         ...
  24
  25         static Test groupname_tests [] = {
  26                 {"groupname_test1", groupname_test1},
  27                 {"groupname_test1", groupname_test2},
  28                 {NULL, NULL}
  29         };
  30
  31         DEFINE_TEST_GROUP_INIT(groupname_tests_init, groupname_tests)
  32
  33 A test implementation should look like:
  34
  35         RESULT groupname_test1()
  36         {
  37                 <perform the test>
  38
  39                 if(test_failed) {
  40                         return FAILED("reason: %s", "this works like printf");
  41                 }
  42
  43                 return OK; /* just NULL, but OK is cute */
  44         }
  45
  46 Once a test group is written, it needs to be added to the groups table
  47 in tests.h:
  48
  49         DEFINE_TEST_GROUP_INIT_H(groupname_tests_init) // same as in impl
  50
  51         static Group test_groups [] = {
  52                 ...
  53                 {"groupname", groupname_tests_init}
  54                 ...
  55         };
  56
  57 ===============================================================================
  58 2. Using the test driver
  59 ===============================================================================
  60
  61 When tests are written, they are rebuilt with make. Two programs will be
  62 built:
  63
  64         test-eglib: the test driver and tests linked against eglib
  65         test-glib:  the test driver and tests linked against system glib-2.0
  66
  67 Each driver program works exactly the same. Running test-eglib will run
  68 the tests against eglib, and test-glib against glib-2.0.
  69
  70 The test driver supports a few options to allow for performance measuring:
  71
  72         --help          show all options and available test groups
  73         --time          time the overall run and report it, even if --quiet is set
  74         --quiet         do not print test results, useful for timing
  75         --iterations N  run all or specified test groups N times
  76
  77 Run "test-eglib --help" for more details.
  78
  79 Example: run the ptrarray test group 100000 times and only print the time
  80          it took to perform all iterations
  81
  82         ./test-eglib -tqi 100000 ptrarray
  83
  84 Example: show single iteration of test output for two groups
  85
  86         ./test-eglib ptrarray hashtable
  87
  88 Example: show test output of all available groups
  89
  90         ./test-eglib
  91
  92 The 'test-both' script can be used to run both test-eglib and test-glib
  93 with the same options back to back:
  94
  95         $ ./test-both -tqi 100000 ptrarray
  96         EGlib Total Time: 1.1961s
  97         GLib Total Time: 0.955957s
  98
  99 test-both also has a nice --speed-compare mode that shows comparison
 100 information about EGlib vs GLib. It can run all tests or specific tests
 101 with a configurable number of iterations. --speed-compare mode always runs
 102 the drivers with -qtni
 103
 104 The syntax for --speed-compare is:
 105
 106         ./test-both --speed-compare [ITERATIONS] [GROUPS...]
 107
 108         $ ./test-both --speed-compare       Runs all tests with default iterations
 109         $ ./test-both --speed-compare 500   Runs all tests with 500 iterations
 110         $ ./test-both --speed-compare ptrarray   Runs ptrarray test with default
 111                                                  iterations
 112
 113