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, similar for
  13 rtf and docbook output.
  14
  15 The runtest.py script responsible for running the tests takes a number of
  16 optional parameters:
  17   --updateref           update the reference files. Should be used in
  18                         combination with -id to update the reference file(s)
  19                         for the given test
  20   --doxygen [DOXYGEN]   path/name of the doxygen executable
  21   --xmllint [XMLLINT]   path/name of the xmllint executable
  22   --id IDS [IDS ...]    run test with number n only (the option can be
  23                         specified to run test with number n only (the option
  24                         can be specified multiple times
  25   --start_id START_ID   run tests starting with number n
  26   --end_id END_ID       run tests ending with number n
  27   --all                 can be used in combination with -updateref to update
  28                         the reference files for all tests.
  29   --inputdir [INPUTDIR]
  30                         input directory containing the tests
  31   --outputdir [OUTPUTDIR]
  32                         output directory to write the doxygen output to
  33   --noredir             disable redirection of doxygen warnings
  34   --pool [POOL]         pool size of multiprocess tests
  35   --xml                 create xml output and check
  36   --rtf                 create rtf output
  37   --docbook             create docbook output and check with xmllint
  38   --xhtml               create xhtml output and check with xmllint
  39   --xmlxsd              create xml output and check with xmllint against xsd
  40   --pdf                 create LaTeX output and create pdf from it
  41   --subdirs             use the configuration parameter CREATE_SUBDIRS=YES
  42   --clang               use CLANG_ASSISTED_PARSING, works only when doxygen
  43                         has been compiled with "use_libclang"
  44   --keep                keep result directories
  45   --cfg CFGS [CFGS ...]
  46                         run test with extra doxygen configuration settings
  47                         (the option may be specified multiple times
  48 In case neither --xml, --xmlxsd, --pdf, --rtf, --docbook or --xhtml is used the
  49 default is set to --xml.
  50
  51 The runtest.pl has the following dependencies on 3rd party tools:
  52 - python  to run the script
  53 - xmllint to normalize the XML output
  54 - diff    to show the differences in case a test fails
  55
  56 Each test file can have a number of special comment lines that are extracted by
  57 the runtest.pl script and take the form:
  58 // <identifier>: 'argument'
  59 Where <identifier> can be one of:
  60 - objective: 'argument' provides the objective for the test (i.e. its purpose)
  61 - check:     'argument' names a file that is generated by doxygen, which should
  62              be compared against the reference.
  63 - config:    'argument' is a line that is added to the default Doxyfile used to
  64              run doxygen on the test file.
  65
  66 Example to run all tests:
  67     python runtest.py
  68
  69 Example to run a test
  70     python runtest.py -id 10
  71
  72 Example to update the reference files for a test
  73     python runtest.py -updateref -id 10
  74
  75 There is also a CMakeLists.txt, which can be used from the build directory
  76 to run all tests by simply invoking 'make tests', to use the specific options use
  77 the flag TEST_FLAGS with make
  78   e.g. make tests TEST_FLAGS="--id=5 --id=10 --pdf --xhtml"