diff options
Diffstat (limited to 'testing/README.txt')
-rw-r--r-- | testing/README.txt | 48 |
1 files changed, 48 insertions, 0 deletions
diff --git a/testing/README.txt b/testing/README.txt new file mode 100644 index 0000000..ee3de59 --- /dev/null +++ b/testing/README.txt @@ -0,0 +1,48 @@ +Doxygen regession test suite +============================ + +This directory contains a set of regression tests. Each test consists of a +file starting with a 3 digit number and a corresponding directory whose name +has the same 3 digit number. The directory contains one or more reference +files that are compared against the XML output produced by doxygen. If the +result is the same, there is no regression and the test passes. If there is a +difference the test fails and the difference (in diff -u format) will be shown. + +The runtest.py script responsible for running the tests takes a number of +optional parameters: +-id n: run test with number n only (the option may be specified + multiple times) default is to run all tests. +-updateref: update the reference files. Should be used in combination + with -id to update the reference file(s) for the given test. +-all: can be used in combination with -updateref to update the + reference files for all tests. +-doxygen exe: run the specified doxygen executable. +-xmllint exe: run the specified xmllint executable. + +The runtest.pl has the following dependenies on 3rd party tools: +- python to run the script +- xmllint to normalize the XML output +- diff to show the differences in case a test fails + +Each test file can have a number of special comment lines that are extracted by +the runtest.pl script and take the form: +// <identifier>: 'argument' +Where <identifier> can be one of: +- objective: 'argument' provides the objective for the test (i.e. its purpose) +- check: 'argument' names a file that is generated by doxygen, which should + be compared against the reference. +- config: 'argument' is a line that is added to the default Doxyfile used to + run doxygen on the test file. + +Example to run all tests: + python runtest.py + +Example to run a test + python runtest.py -id 10 + +Example to update the reference files for a test + python runtest.py -updateref -id 10 + +There is also a CMakeLists.txt, which can be used from the build directory +to run all tests by simply invoking 'make tests'. + |