root / tags / 1.0.8 / xapian-core / docs / tests.html

Revision 8160, 5.2 kB (checked in by olly, 21 months ago)

* ./: svn:eol-style not svn:eolstyle.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<HTML>
3<HEAD>
4<TITLE>Xapian: Tests</TITLE>
5</HEAD>
6<BODY BGCOLOR="white" TEXT="black">
7
8<H1>Tests</H1>
9
10<H2>Contents</H2>
11
12<ol>
13<li> <A HREF="#running">A Brief Guide to Running Tests</A>
14<li> <A HREF="#writing">A Brief Guide to Writing Tests</A>
15<li> <A HREF="#quartz">Quartz Backend Tests</A>
16</ol>
17
18<H2><A NAME="running">A Brief Guide to Running Tests</A></H2>
19
20<P>After a successful "<code>make</code>", try "<code>make check</code>".
21
22<P>It's possible to run test cases individually, and get verbose output
23when one fails, etc.  For more information, see the "Running test programs"
24section of HACKING.
25
26<H2><A NAME="writing">A Brief Guide to Writing Tests</A></H2>
27
28<P>Test programs live in <code>tests/</code>.  They mostly use a standard test harness,
29in <code>tests/harness/</code>, which wraps each test,
30reports results, and generally packages things up nicely.  The test harness
31counts how many testcases pass/fail/skip, catches signals and unhandled exceptions,
32and so
33forth.  It can also also check for memory leaks and accesses to
34uninitialised values by making use of valgrind, for platforms which valgrind
35supports (configure automatically enables use of valgrind if a suitably
36recent version is detected).
37
38<P>A typical test program has three parts: the tests themselves (at the top),
39a table of tests (at the bottom), and a tiny main which sets the test harness
40in motion.  It uses the table to figure out what the tests are called, and
41what function to call to run them.
42
43<P>The most important test system for most people will be <code>apitest</code>. This also
44uses the test harness, but has several tables of tests to be run depending what
45facilities each backend supports.  A lot of the work is done by macros and
46helper functions, which may make it hard to work out quite what is going on,
47but make life easier once you've grasped what's going on.  The <code>main()</code>
48function and other
49bits are in <code>apitest.cc</code>, and tests themselves are in various other C++ files
50starting api_. Each one of these has its own tables for various different
51groups of tests (eg: <code>api_db.cc</code>, which performs tests on the API that require a
52database backend, has basic tests, a few specialised groups that only contain
53one or two tests, tests that require a writable database, tests that require a
54local database, and finally tests that require a remote database).
55
56<P>To add a new api test, figure out what the test will be dependent on
57and put it in the appropriate place (eg: if adding a test for a bug
58that occurs while writing to a database, you want a writable
59database, so you add a test to <code>api_db.cc</code> and reference it in the
60<code>writabledb_tests</code> table).
61
62<P>Currently, there's <code>api_nodb.cc</code> (no db required, largely testing query
63construction and boundary conditions), <code>api_posdb.cc</code> (db with
64positional information required) and <code>api_db.cc</code> (everything else, with
65lots of subgroups of tests). It's easiest to base a test on an
66existing one.
67
68<P>You'll notice in <code>apitest.cc</code> that it runs all appropriate test groups against
69each backend that is being built. The backends are inmemory,
70quartz, flint, remote and remotetcp. If you need to create a new test group
71with different
72requirements to any current ones, put it in the appropriate api_ file (or
73create a new one, and add it into Makefile.am) and remember to add the group to
74all pertinent backends in <code>apitest.cc</code>.
75
76<P>Incidentally, when fixing bugs, it's often better to write the test
77before fixing the bug. Firstly, it's easier to assure yourself that
78the bug is (a) genuine, and (b) fixed, because you see the test go
79from fail to pass (though sometimes you don't get the testcase quite right,
80so this isn't doesn't always work as well as it should).
81Secondly you're more likely to write the test
82carefully, because once you've fixed something there's often a feeling
83that you should commit it for the good of the world, which tends to
84distract you.
85
86<H2><A NAME="quartz">Quartz Backend Tests</A></H2>
87
88<P>Tests of the btree's functionality go in <code>tests/btreetest.cc</code>;
89tests of quartz itself in <code>tests/quartztest.cc</code>.
90
91<P>The framework is done for you, so you don't need to worry about that much.
92You are responsible for doing two things:
93
94<ol>
95<li> writing a minimal test or tests for the feature
96<li> adding that test to the list of tests to be run
97</ol>
98
99Adding the test is simple. There's a test_desc array in each file that comprises a
100set of tests (I'll come to that in a minute), and you just add another
101entry. The entry is an array consisting of a name for the test and a
102pointer to the function that is the test. Easy.
103
104<P>Look at the bottom of <code>tests/btreetest.cc</code> for the test_desc array. Now look up about
10520 lines to where the test functions are defined.
106You need to write a function like these which will return true or false
107depending on whether it failed or not.
108
109<P>In addition, there are a bunch of macros to help you perform standards testing
110tasks. Things like
111TEST_EQUAL are all in <code>tests/harness/testsuite.h</code>. They're pretty simple to
112use.
113
114<!-- FOOTER $Author$ $Date$ $Id$ -->
115</BODY>
116</HTML>
Note: See TracBrowser for help on using the browser.