← Back to branch summary

~ubuntu-branches/ubuntu/raring/clucene-core/raring-proposed

« back to all changes in this revision

Viewing changes to src/test/README

  • Committer: Package Import Robot
  • Author(s): Fathi Boudra
  • Date: 2012-08-11 09:33:38 UTC
  • mfrom: (1.1.5)
  • Revision ID: package-import@ubuntu.com-20120811093338-fgrx41ftqew3qt6a
Tags: 2.3.3.4-1
http://bugs.debian.org/661703
* New upstream release (Closes: #661703).
* Convert package to multiarch.
* Drop obsolete patches:
  - 01_add_missing_include_bug505667.diff
  - 02_posixness_fix_bug530308.diff
* Add patches:
  - Fixing_ZLIB_configuration_in_shared_CMakeLists.patch
  - Fix-pkgconfig-file-by-adding-clucene-shared-library.patch
  - Install-contribs-lib.patch
  - multiarch.patch
* Update debian/compat: bump to 8.
* Update debian/control:
  - update build dependencies (add cmake, libboost-dev and libz-dev).
  - bump Standards-Version to 3.9.3.
  - rename packages due to ABI bump: libclucene0ldbl -> libclucene-core1.
  - add libclucene-contribs1 package.
* Update debian/rules:
  - rewrite to use CMake.
  - add multiarch support.

Show diffs side-by-side

added added

removed removed

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