xapian-core/docs/tests.rst

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