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'.
+