About units test facility
============================================================

Masatake YAMATO <yamato@redhat.com>

Background
------------------------------------------------------------

Exuberant ctags has a test facility. Main aim of the facility is
detecting regression. All files under Tests directory are given as
input for old and new version of ctags commands.  The output tags
files of both versions are compared.

The units test facility I describe here takes a different approach. An
input file and an expected output file are given by a contributor of a
language parser. The units test facility runs ctags command with the
input file and compares its output and the expected output file.

If a contributor sends a patch which may improve a language parser,
and if a reviewer is not familiar with that language, s/he cannot
evaluate it.

Unit test files, the pair of input file and expected output file may
be able to explain the intent of patch well; and may help the
reviewer.

How to write a test case
------------------------------------------------------------

The test facility recognizes an input file and an expected
output file by patterns of file name. Each test case should
have its own directory under Units directory.

Units/TEST/input.* [requisite]

	Input file name must have a "input" as basename. TEST
	part should explain the test case well.

Units/TEST/expected.tags [requisite]

	Expected output file must have a name "expected.tags". It
	should be the same directory of the input file.

Units/TEST/args.ctags [optional]

	'-o -' is used as default optional argument when running a
	unit test ctags. If you want to add more options, enumerate
	options in args.ctags file. This file is an optional.

filter-*.* [optional]

	TBW

Example of files
------------------------------------------------------------

See Units/c-sample/input.c and Units/c-sample/expected.

How to run unit tests
------------------------------------------------------------

test.units target is added to testing.mak.


	 $ make -f testing.mak test.units

The result of unit tests is reported by lines.

During testing OUTPUT, EXPECTED and DIFF files are generated for each
test case directory. These are removed when the unit test is "Passed".
If the result is "Failed", it is kept for debugging. Following
command line can clean up these generated files at once:

         $ make -f testing.mak clean-test

Example of running
------------------------------------------------------------

	$ make -f testing.mak test.units
	Testing Units/cpp-type-alias-with-using-keyword...Passed
	Testing Units/c-sample...Passed

Acknowledgements
------------------------------------------------------------

The file name rule is suggested by Maxime Coste <frrrwww@gmail.com>.