Testing the libraries¶
Both xapian-core
and xapian-letor
have automated test suites
covering their APIs and various internals of the API
implementations. They are implemented using the same C++ test harness,
and so have similar features and tests in both should feel familiar
once you get used to one.
There are a few environment variables which the test harness checks for which you might find useful:
XAPIAN_TESTSUITE_SIG_DFL
- By default, the testsuite harness catches signals and handles them
gracefully - the current test is failed, and the testsuite moves onto the
next test. If you want to suppress this (some debugging tools may work
better if the signal is not caught) set the environment variable
XAPIAN_TESTSUITE_SIG_DFL
to any value to prevent the testsuite harness from installing its own signal handling. XAPIAN_TESTSUITE_OUTPUT
By default, the testsuite harness uses ANSI escape sequences to give colour output if stdout is a tty. You can disable this feature by setting
XAPIAN_TESTSUITE_OUTPUT=plain
. Alternatively, piping the output, such as throughcat
ormore
, will have the same effect.Auto-detection can be explicitly specified with
XAPIAN_TESTSUITE_OUTPUT=auto
(or empty). Any other value forces the use of colour.Colour output is always disabled on Microsoft Windows, so
XAPIAN_TESTSUITE_OUTPUT
has no effect there.XAPIAN_TESTSUITE_LD_PRELOAD
The runtest script will add this to
LD_PRELOAD
if it is set, allowing you to easily loadLD_PRELOAD
libraries when running the testsuite. The original intended use was to allow use of libeatmydata which makesfsync
and related calls no-ops, but configure now checks for the eatmydata wrapper script and this is used automatically.However, there may be other
LD_PRELOAD
libraries which are useful, so we’ve left the machinery in place.
Running test programs¶
To run all tests, use make check
. You can also run just the subset of
tests which exercise the inmemory, remote progserver, remote TCP,
multi-database, glass or honey backends using make check-inmemory
,
make check-remoteprog
, make check-remotetcp
, make check-multi
,
make check-glass
or make check-honey
respectively.
Also, make check-remote
will run the tests on both variants of the remote
backend, and make check-none
will run those tests which don’t use any
backend. These are handy shortcuts when doing development work on a particular
backend.
Running individual tests¶
The runtest script (in the tests subdirectory) takes care of the details of running the test programs (including setting up the environment so they work when srcdir != builddir and handling libtool dynamically linked binaries). To run a test program by hand (rather than via make) just use:
./runtest ./apitest
You can specify options and arguments. Individual test programs optionally
take one or more test names as arguments, and you can also pass -v
to get
more verbose output from failing tests, e.g.:
./runtest ./apitest -v deldoc1
If the number of the test is omitted, all tests with that basename are run, so to run deldoc1, deldoc2, etc:
./runtest ./apitest deldoc
Running under a debugger or other tool¶
You can also use runtest to run a test program under gdb (or most other tools):
./runtest gdb ./apitest -v deldoc1
./runtest valgrind ./apitest -v deldoc1
Some test programs take special arguments - for example, you can restrict
apitest to the glass backend using -bglass
.
Speeding up the testsuite with eatmydata¶
The testsuite does a lot of small database operations, and the calls to fsync,
fdatasync, etc which Xapian makes by default can slow down testsuite runs
substantially. There’s a handy LD_PRELOAD
library called eatmydata, which can help here,
by turning fsync and related calls into no-ops.
You need a version of eatmydata with the eatmydata wrapper script (version 37 or newer), and then configure should auto-detect it and it’ll get used when running the testsuite (via runtest). If you wish to disable this auto-detection for some reason, you can run configure with:
./configure EATMYDATA=
Or you can disable use of eatmydata during a particular run of “make check” like so:
make check EATMYDATA=
Or disable it while running a test directly (under sh or bash):
EATMYDATA= ./runtest ./apitest