[cairo] New cairo regression test

[Carl Worth]

I've just begun working on a test suite for cairo. This should be quite
helpful for tracking bugs, preparing releases, and preventing regression
errors from creeping in.

What I have so far is committed in the cairo/test directory. Running it
should be as simple as:

	make check

Any known bugs are marked as expected failures. The idea here is to draw
special attention to regression errors. From now on, before any code is
committed to cairo, the tests should be run to verify that there are no
unexpected failures. If there are any, they should be examined more
closely and fixed if necessary before committing.

Then, before releasing we can eliminate all failures.

I have been doing something similar with an SVG suite for some time, and
now that more people are committing, I wanted to put together something
we could all use, and that relied only on cairo itself.

The test suite is implemented as simple programs with some shared
code. The guts of each test is a single function like the following:

	void draw (cairo_t *cr, int width, int height)

The results of this function are saved as a PNG and compared
pixel-by-pixel with a reference PNG image. It should be fairly simple to
augment the system in the future to test other backends such as the X
backend, (and without having to modify the individual tests).

This environment is similar to cairo_snippets, but with a bit less code
generation so there is more flexibility, (eg. a single program can have
multiple functions and multiple tests). Also, unlike cairo_snippets,
cairo/test does not change the default transformation, line width,
etc. One drawback of cairo/test is that there's a bunch of fiddling
needed in Makefile.am for every new test. The cairo_snippets stuff is
much easier to use in that regard, so some help in fixing that would be
appreciated.

I'm optimistic that this test suite will help people to submit high
quality bug reports, (eg. a program along with the expected output
image). These are precisely the kinds of bug reports I'd like to work
with. We can accept reports on this mailing list, and anyone that would
like it, can get CVS commit access for directly submission of
reports. I'm also keeping bug history directly in comments in the tests
where it can be viewed fairly easily by anyone, (and within released tar
files).

I've only got a couple of tests in place so far. I'm planning to go
through cairo/BUGS and write tests for all know bugs. I'll also push
through my personal backlog of list messages to add tests for all the
bugs mentioned there. Finally, we should add tests to cover as much of
the implementation as possible. If anyone wants to help flesh out these
tests, that would be most welcome.

The new cairo/tests/README is included below.

Any feedback is most welcome.

-Carl

Regression test suite for cairo.

Using this test should be as simple as running:

	make check

assuming that the cairo distribution in the directory above has been
configured and built. The test suite here goes through some effort to
run against the locally compiled library rather than any installed
version.

The test suite needs to be run before any code is committed and before
any release. Here are the rules governing the use of the suite:

Before committing
-----------------

All tests should return a result of PASS or XFAIL. The XFAIL results
indicate known bugs. The final message should be one of the following:

	All XX tests behaved as expected (YY expected failures)
	All XX tests passed

If any tests have a status of FAIL, then the new code has caused a
regression error which should be fixed before the code is committed.

When a new bug is found
-----------------------
A new test case should be added by imitating the style of an existing
test. This means adding the following files:

	new_bug.c
	new_bug-ref.png

Where new_bug.c is a minimal program to demonstrate the bug, following
the style of existing tests. The new_bug-ref.png image should contain
the desired result of new_bug.c if the bug were fixed.

Makefile.am should be edited, adding new_bug.c to both the TESTS and
XFAIL_TESTS lists.

When a new feature is added
---------------------------
It's important for the regression suite to keep pace with development
of the library. So a new test should be added for each new
feature. The work involved is similar the work described above for new
bugs. The only distinction is that the test is expected to pass so it
should not be added to the XFAIL_TESTS list.


When a bug is fixed
-------------------
The fix should be verified by running the test suite which should
result in an "unexpected pass" for the test of interest. Rejoice as
appropriate, then remove the relevant file name from the XFAIL_TESTS
variable in Makefile.am.

Before releasing
----------------
All tests should return a result of PASS meaning all known bugs are
fixed, resulting in the happy message:

	All XX tests passed