← Back to branch summary

~ubuntu-branches/ubuntu/feisty/apache2/feisty

« back to all changes in this revision

Viewing changes to srclib/apr/test/README

  • Committer: Bazaar Package Importer
  • Author(s): Andreas Barth
  • Date: 2006-12-09 21:05:45 UTC
  • mfrom: (0.6.1 upstream)
  • Revision ID: james.westby@ubuntu.com-20061209210545-h70s0xaqc2v8vqr2
Tags: 2.2.3-3.2
http://bugs.debian.org/396265
* Non-maintainer upload.
* 043_ajp_connection_reuse: Patch from upstream Bugzilla, fixing a critical
  issue with regard to connection reuse in mod_proxy_ajp.
  Closes: #396265

Show diffs side-by-side

added added

removed removed

Lines of Context:
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
Running individual tests
 
63
---------------------------------
 
64
 
 
65
It is not possible to build individual tests, however it is possible to
 
66
run individual tests.  When running the test suite, specify the name of the
 
67
tests that you want to run on the command line.  For example:
 
68
 
 
69
        ./testall teststr testrand
 
70
 
 
71
Will run the Strings and Random generator tests.
 
72
 
 
73
Reading the test suite output
 
74
-----------------------------
 
75
 
 
76
Once you run the test suite, you will get output like:
 
77
 
 
78
All APR Tests:
 
79
    Test Strings:       ....
 
80
    Test Time:  ............
 
81
 
 
82
16 tests run:  16 passed, 0 failed, 0 not implemented.
 
83
 
 
84
Known test failures are documented in ../STATUS.
 
85
 
 
86
There are a couple of things to look at with this.  First, if you look at the
 
87
first function in this document, you should notice that the string passed to
 
88
the CuSuiteNew function is in the output.  That is why the string should
 
89
explain the feature you are testing.
 
90
 
 
91
Second, this test passed completely.  This is obvious in two ways.  First, and
 
92
most obvious, the summary line tells you that 16 tests were run and 16 tests
 
93
passed.  However, the results can also be found in the lines above.  Every
 
94
'.' in the output represents a passed test.
 
95
 
 
96
If a test fails, the output will look like:
 
97
 
 
98
All APR Tests:
 
99
    Test Strings:       ....
 
100
    Test Time:  ..F.........
 
101
 
 
102
16 tests run:  15 passed, 1 failed, 0 not implemented.
 
103
 
 
104
This is not very useful, because you don't know which test failed.  However,
 
105
once you know that a test failed, you can run the suite again, with the
 
106
-v option.  If you do this, you will get something like:
 
107
 
 
108
All APR Tests:
 
109
    Test Strings:       ....
 
110
    Test Time:  ..F.........
 
111
 
 
112
16 tests run:  15 passed, 1 failed, 0 not implemented.
 
113
Failed tests:
 
114
1) test_localstr: assert failed
 
115
 
 
116
In this case, we know the test_localstr function failed, and there is an
 
117
Assert in this that failed (I modified the test to fail for this document).
 
118
Now, you can look at what that test does, and why it would have failed.
 
119
 
 
120
There is one other possible output for the test suite (run with -v):
 
121
 
 
122
All APR Tests:
 
123
    Test Strings:       ....
 
124
    Test Time:  ..N.........
 
125
 
 
126
16 tests run:  15 passed, 0 failed, 1 not implemented.
 
127
 
 
128
Not Implemented tests:
 
129
 
 
130
Not Implemented tests:
 
131
1) test_localstr: apr_time_exp_lt not implemented on this platform
 
132
 
 
133
The 'N' means that a function has returned APR_ENOTIMPL.  This should be 
 
134
treated as an error, and the function should be implemented as soon as
 
135
possible.
 
136
 
 
137
Adding New test Suites to the full driver
 
138
-------------------------------------------
 
139
 
 
140
To add a new Suite to the full driver, you must make a couple of modifications.
 
141
 
 
142
1)  Edit test_apr.h, and add the prototype for the function.
 
143
2)  Edit testall.c, and add the function and name to the tests array.
 
144
3)  Edit Makefile.in, and add the .lo file to the testall target.
 
145
 
 
146
Once those four things are done, your tests will automatically be added
 
147
to the suite.
 
148
 
 
149
Writing tests
 
150
-------------
 
151
 
 
152
There are a couple of rules for writing good tests for the test suite.
 
153
 
 
154
1)  All tests can determine for themselves if it passed or not.  This means
 
155
that there is no reason for the person running the test suite to interpret
 
156
the results of the tests.
 
157
2)  Never use printf to add to the output of the test suite.  The suite
 
158
library should be able to print all of the information required to debug
 
159
a problem.
 
160
3)  Functions should be tested with both positive and negative tests.  This
 
161
means that you should test things that should both succeed and fail.
 
162
4)  Just checking the return code does _NOT_ make a useful test.  You must
 
163
check to determine that the test actually did what you expected it to do.
 
164
 
 
165
An example test
 
166
---------------
 
167
 
 
168
Finally, we will look at a quick test:
 
169
 
 
170
/* All tests are passed a CuTest variable.  This is how the suite determines
 
171
 * if the test succeeded or failed.
 
172
 */
 
173
static void test_localstr(CuTest *tc)
 
174
{
 
175
    apr_status_t rv;
 
176
    apr_time_exp_t xt;
 
177
    time_t os_now;
 
178
 
 
179
    rv = apr_time_exp_lt(&xt, now);
 
180
    os_now = now / APR_USEC_PER_SEC;
 
181
   
 
182
    /* If the function can return APR_ENOTIMPL, then you should check for it.
 
183
     * This allows platform implementors to know if they have to implement
 
184
     * the function.
 
185
     */
 
186
    if (rv == APR_ENOTIMPL) {
 
187
        CuNotImpl(tc, "apr_time_exp_lt");
 
188
    }
 
189
 
 
190
    /* It often helps to ensure that the return code was APR_SUCESS.  If it
 
191
     * wasn't, then we know the test failed.
 
192
     */
 
193
    CuAssertTrue(tc, rv == APR_SUCCESS);
 
194
 
 
195
    /* Now that we know APR thinks it worked properly, we need to check the
 
196
     * output to ensure that we got what we expected.
 
197
     */
 
198
    CuAssertStrEquals(tc, "2002-08-14 12:05:36.186711 -25200 [257 Sat] DST",
 
199
                      print_time(p, &xt));
 
200
}
 
201
 
 
202
Notice, the same test can fail for any of a number of reasons.  The first 
 
203
test to fail ends the test.
 
204
 
 
205
CuTest
 
206
------
 
207
 
 
208
CuTest is an open source test suite written by Asim Jalis.  It has been 
 
209
released under the zlib/libpng license.  That license can be found in the
 
210
CuTest.c and CuTest.h files.
 
211
 
 
212
The version of CuTest that is included in the APR test suite has been modified
 
213
from the original distribution in the following ways:
 
214
 
 
215
1)  The original distribution does not have a -v flag, the details are always
 
216
printed.
 
217
2)  The NotImplemented result does not exist.
 
218
3)  SuiteLists do not exist.  In the original distribution, you can add suites
 
219
to suites, but it just adds the tests in the first suite to the list of tests
 
220
in the original suite.  The output wasn't as detailed as I wanted, so I created
 
221
SuiteLists.
 
222
 
 
223
The first two modifications have been sent to the original author of CuTest,
 
224
but they have not been integrated into the base distribution.  The SuiteList
 
225
changes will be sent to the original author soon.
 
226
 
 
227
The modified version of CuTest is not currently in any CVS or Subversion
 
228
server.  In time, it will be hosted at rkbloom.net.
 
229
 
 
230
There are currently no docs for how to write tests, but the teststr and 
 
231
testtime programs should give an idea of how it is done.  In time, a document
 
232
should be written to define how tests are written.
 
233