rubbos/app/httpd-2.0.64/srclib/apr/test/README

   1 Writing APR tests
   2
   3 All APR tests should be executable in 2 ways, as an individual program, or
   4 as a part of the full test suite.  The full test suite is controlled with
   5 the testall program.  At the beginning of the testall.c file, there is an
   6 array of functions called tests.  The testall program loops through this
   7 array calling each function.  Each function returns a CuSuite variable, which
   8 is then added to the SuiteList.  Once all Suites have been added, the SuiteList
   9 is executed, and the output is printed to the screen.  All functions in the
  10 array should follow the same basic format:
  11
  12 The Full Suite
  13 --------------
  14
  15 /* The driver function.  This must return a CuSuite variable, which will
  16  * then be used to actually run the tests.  Essentially, all Suites are a
  17  * collection of tests.  The driver will take each Suite, and put it in a
  18  * SuiteList, which is a collection of Suites.
  19  */
  20 CuSuite *testtime(void)
  21 {
  22     /* The actual suite, this must be created for each test program.  Please
  23      * give it a useful name, that will inform the user of the feature being
  24      * tested.
  25      */
  26     CuSuite *suite = CuSuiteNew("Test Time");
  27
  28     /* Each function must be added to the suite.  Each function represents
  29      * a single test.  It is possible to test multiple features in a single
  30      * function, although no tests currently do that.
  31      */
  32     SUITE_ADD_TEST(suite, test_now);
  33     SUITE_ADD_TEST(suite, test_gmtstr);
  34     SUITE_ADD_TEST(suite, test_localstr);
  35     SUITE_ADD_TEST(suite, test_exp_get_gmt);
  36     SUITE_ADD_TEST(suite, test_exp_get_lt);
  37     SUITE_ADD_TEST(suite, test_imp_gmt);
  38     SUITE_ADD_TEST(suite, test_rfcstr);
  39     SUITE_ADD_TEST(suite, test_ctime);
  40     SUITE_ADD_TEST(suite, test_strftime);
  41     SUITE_ADD_TEST(suite, test_strftimesmall);
  42     SUITE_ADD_TEST(suite, test_exp_tz);
  43     SUITE_ADD_TEST(suite, test_strftimeoffset);
  44
  45     /* You must return the suite so that the driver knows which suites to
  46      * run.
  47      */
  48     return suite;
  49 }
  50
  51 Building the full driver
  52 ------------------------
  53
  54 All you need to do to build the full driver is run:
  55
  56     make testall
  57
  58 To run it, run:
  59
  60     ./testall
  61
  62 Caveats
  63 -------
  64
  65 Currently, some tests are known to fail in certain circumstances:
  66
  67  * 'testpoll' opens 64 sockets concurrently; ensure that resource
  68 limits are high enough to allow this (using ulimit or limit); for
  69 instance, Solaris <=2.7 and HP-UX 11.00 both set the limit to <=64 by
  70 default
  71
  72  * 'testipsub' will tickle the Solaris 8 getaddrinfo() IPv6
  73 bug, causing the test to hang.  Configure with --disable-ipv6 if using
  74 an unpatched Solaris 8 installation.
  75
  76  * The 'testdso' tests will not work if configured with
  77 --disable-shared since the loadable modules cannot be built.
  78
  79 Running individual tests
  80 ---------------------------------
  81
  82 It is not possible to build individual tests, however it is possible to
  83 run individual tests.  When running the test suite, specify the name of the
  84 tests that you want to run on the command line.  For example:
  85
  86         ./testall teststr testrand
  87
  88 Will run the Strings and Random generator tests.
  89
  90 Reading the test suite output
  91 -----------------------------
  92
  93 Once you run the test suite, you will get output like:
  94
  95 All APR Tests:
  96     Test Strings:       ....
  97     Test Time:  ............
  98
  99 16 tests run:  16 passed, 0 failed, 0 not implemented.
 100
 101 There are a couple of things to look at with this.  First, if you look at the
 102 first function in this document, you should notice that the string passed to
 103 the CuSuiteNew function is in the output.  That is why the string should
 104 explain the feature you are testing.
 105
 106 Second, this test passed completely.  This is obvious in two ways.  First, and
 107 most obvious, the summary line tells you that 16 tests were run and 16 tests
 108 passed.  However, the results can also be found in the lines above.  Every
 109 '.' in the output represents a passed test.
 110
 111 If a test fails, the output will look like:
 112
 113 All APR Tests:
 114     Test Strings:       ....
 115     Test Time:  ..F.........
 116
 117 16 tests run:  15 passed, 1 failed, 0 not implemented.
 118
 119 This is not very useful, because you don't know which test failed.  However,
 120 once you know that a test failed, you can run the suite again, with the
 121 -v option.  If you do this, you will get something like:
 122
 123 All APR Tests:
 124     Test Strings:       ....
 125     Test Time:  ..F.........
 126
 127 16 tests run:  15 passed, 1 failed, 0 not implemented.
 128 Failed tests:
 129 1) test_localstr: assert failed
 130
 131 In this case, we know the test_localstr function failed, and there is an
 132 Assert in this that failed (I modified the test to fail for this document).
 133 Now, you can look at what that test does, and why it would have failed.
 134
 135 There is one other possible output for the test suite (run with -v):
 136
 137 All APR Tests:
 138     Test Strings:       ....
 139     Test Time:  ..N.........
 140
 141 16 tests run:  15 passed, 0 failed, 1 not implemented.
 142
 143 Not Implemented tests:
 144
 145 Not Implemented tests:
 146 1) test_localstr: apr_time_exp_lt not implemented on this platform
 147
 148 The 'N' means that a function has returned APR_ENOTIMPL.  This should be
 149 treated as an error, and the function should be implemented as soon as
 150 possible.
 151
 152 Adding New test Suites to the full driver
 153 -------------------------------------------
 154
 155 To add a new Suite to the full driver, you must make a couple of modifications.
 156
 157 1)  Edit test_apr.h, and add the prototype for the function.
 158 2)  Edit testall.c, and add the function and name to the tests array.
 159 3)  Edit Makefile.in, and add the .lo file to the testall target.
 160
 161 Once those four things are done, your tests will automatically be added
 162 to the suite.
 163
 164 Writing tests
 165 -------------
 166
 167 There are a couple of rules for writing good tests for the test suite.
 168
 169 1)  All tests can determine for themselves if it passed or not.  This means
 170 that there is no reason for the person running the test suite to interpret
 171 the results of the tests.
 172 2)  Never use printf to add to the output of the test suite.  The suite
 173 library should be able to print all of the information required to debug
 174 a problem.
 175 3)  Functions should be tested with both positive and negative tests.  This
 176 means that you should test things that should both succeed and fail.
 177 4)  Just checking the return code does _NOT_ make a useful test.  You must
 178 check to determine that the test actually did what you expected it to do.
 179
 180 An example test
 181 ---------------
 182
 183 Finally, we will look at a quick test:
 184
 185 /* All tests are passed a CuTest variable.  This is how the suite determines
 186  * if the test succeeded or failed.
 187  */
 188 static void test_localstr(CuTest *tc)
 189 {
 190     apr_status_t rv;
 191     apr_time_exp_t xt;
 192     time_t os_now;
 193
 194     rv = apr_time_exp_lt(&xt, now);
 195     os_now = now / APR_USEC_PER_SEC;
 196
 197     /* If the function can return APR_ENOTIMPL, then you should check for it.
 198      * This allows platform implementors to know if they have to implement
 199      * the function.
 200      */
 201     if (rv == APR_ENOTIMPL) {
 202         CuNotImpl(tc, "apr_time_exp_lt");
 203     }
 204
 205     /* It often helps to ensure that the return code was APR_SUCESS.  If it
 206      * wasn't, then we know the test failed.
 207      */
 208     CuAssertTrue(tc, rv == APR_SUCCESS);
 209
 210     /* Now that we know APR thinks it worked properly, we need to check the
 211      * output to ensure that we got what we expected.
 212      */
 213     CuAssertStrEquals(tc, "2002-08-14 12:05:36.186711 -25200 [257 Sat] DST",
 214                       print_time(p, &xt));
 215 }
 216
 217 Notice, the same test can fail for any of a number of reasons.  The first
 218 test to fail ends the test.
 219
 220 CuTest
 221 ------
 222
 223 CuTest is an open source test suite written by Asim Jalis.  It has been
 224 released under the zlib/libpng license.  That license can be found in the
 225 CuTest.c and CuTest.h files.
 226
 227 The version of CuTest that is included in the APR test suite has been modified
 228 from the original distribution in the following ways:
 229
 230 1)  The original distribution does not have a -v flag, the details are always
 231 printed.
 232 2)  The NotImplemented result does not exist.
 233 3)  SuiteLists do not exist.  In the original distribution, you can add suites
 234 to suites, but it just adds the tests in the first suite to the list of tests
 235 in the original suite.  The output wasn't as detailed as I wanted, so I created
 236 SuiteLists.
 237
 238 The first two modifications have been sent to the original author of CuTest,
 239 but they have not been integrated into the base distribution.  The SuiteList
 240 changes will be sent to the original author soon.
 241
 242 The modified version of CuTest is not currently in any CVS or Subversion
 243 server.  In time, it will be hosted at rkbloom.net.
 244
 245 There are currently no docs for how to write tests, but the teststr and
 246 testtime programs should give an idea of how it is done.  In time, a document
 247 should be written to define how tests are written.
 248