testing/README.txt

   1 Doxygen regression test suite
   2 ============================
   3
   4 This directory contains a set of regression tests. Each test consists of a
   5 file starting with a 3 digit number and a corresponding directory whose name
   6 has the same 3 digit number. The directory contains one or more reference
   7 files that are compared against the XML output produced by doxygen. If the
   8 result is the same, there is no regression and the test passes. If there is a
   9 difference the test fails and the difference (in diff -u format) will be shown.
  10 It is also possible to see whether or not the test can be built to a xhtml set
  11 of files (and tested against a DTD), it is also possible to create a pdf file
  12 for each test to see if the LaTeX / pdf generation is possible.
  13
  14 The runtest.py script responsible for running the tests takes a number of
  15 optional parameters:
  16   --updateref           update the reference data for a test
  17   --doxygen [DOXYGEN]   path/name of the doxygen executable
  18   --xmllint [XMLLINT]   path/name of the xmllint executable
  19   --id IDS [IDS ...]    id of the test to perform
  20   --start_id START_ID   run tests starting with number n
  21   --end_id END_ID       run tests ending with number n
  22   --all                 perform all tests
  23   --inputdir [INPUTDIR]
  24                         input directory containing the tests
  25   --outputdir [OUTPUTDIR]
  26                         output directory to write the doxygen output to
  27   --noredir             disable redirection of doxygen warnings
  28   --xml                 create xml output and check
  29   --rtf                 create rtf output
  30   --docbook             create docbook output and check with xmllint
  31   --xhtml               create xhtml output and check with xmllint
  32   --pdf                 create LaTeX output and create pdf from it
  33   --subdirs             use the configuration parameter CREATE_SUBDIRS=YES
  34   --keep                keep result directories
  35   --cfg CFGS [CFGS ...] run test with extra doxygen configuration settings
  36                         (the option may be specified multiple times
  37 In case neither --xml, --pdf, --rtf, --docbook or --xhtml is used the default is set to --xml.
  38
  39 The runtest.pl has the following dependencies on 3rd party tools:
  40 - python  to run the script
  41 - xmllint to normalize the XML output
  42 - diff    to show the differences in case a test fails
  43
  44 Each test file can have a number of special comment lines that are extracted by
  45 the runtest.pl script and take the form:
  46 // <identifier>: 'argument'
  47 Where <identifier> can be one of:
  48 - objective: 'argument' provides the objective for the test (i.e. its purpose)
  49 - check:     'argument' names a file that is generated by doxygen, which should
  50              be compared against the reference.
  51 - config:    'argument' is a line that is added to the default Doxyfile used to
  52              run doxygen on the test file.
  53
  54 Example to run all tests:
  55     python runtest.py
  56
  57 Example to run a test
  58     python runtest.py -id 10
  59
  60 Example to update the reference files for a test
  61     python runtest.py -updateref -id 10
  62
  63 There is also a CMakeLists.txt, which can be used from the build directory
  64 to run all tests by simply invoking 'make tests', to use the specific options use
  65 the flag TEST_FLAGS with make
  66   e.g. make tests TEST_FLAGS="--id=5 --id=10 --pdf --xhtml"