[librsvg/rustification] tests: Add a README.md; make rsvg-test.c's test names more clear

[Federico Mena Quintero <federico src gnome org>]

commit a41283921856514d0c44f1dc5e69f1177707b95a
Author: Federico Mena Quintero <federico gnome org>
Date:   Thu Nov 3 08:39:41 2016 -0600

    tests: Add a README.md; make rsvg-test.c's test names more clear
    
    We have a new README.md that says how the tests work and how to deal
    with failed tests.
    
    Additionally, the GTest test names that rsvg-test produces are now
    easier to understand.  The test name
    
      /rsvg-test/reftests/foo/bar.svg
    
    will actually match the file
    
      fixtures/reftests/foo/bar.svg
    
    Whereas before, the test for that file would be called
    "/rsvg/reftest/foo/bar.svg", which isn't entirely obvious.

 .gitignore        |    1 -
 tests/README.md   |  171 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 tests/rsvg-test.c |    4 +-
 3 files changed, 173 insertions(+), 3 deletions(-)
---
diff --git a/.gitignore b/.gitignore
index b41e047..4180e23 100644
--- a/.gitignore
+++ b/.gitignore
@@ -55,7 +55,6 @@ gdk-pixbuf-loader/rsvg-loader
 tests/dimensions
 tests/pdiff/perceptualdiff
 tests/rsvg-test
-tests/rsvg-test.html
 tests/rsvg-test.log
 tests/styles
 tools/test-memory
diff --git a/tests/README.md b/tests/README.md
new file mode 100644
index 0000000..dd0289b
--- /dev/null
+++ b/tests/README.md
@@ -0,0 +1,171 @@
+Librsvg test suite
+==================
+
+Librsvg's test harness is built upon Glib's GTest utility functions.
+These let you define tests in the C language.
+
+There are three different styles of tests:
+
+* crash - Ensures that loading and parsing (but not rendering) a
+  particular SVG doesn't yield a GError.
+
+* styles - Loads and parses an SVG, and checks that a particular SVG
+  object has a certain style.
+
+* rsvg-test - The main test suite; loads, parses, and renders SVGs and
+  compares the results against reference PNG images.
+
+These are all "black box tests": they run the library with its public
+API, and test the results.  They do not test the library's internals;
+just the output.
+
+Additionally, the library's source code has smaller unit tests for
+particular sections of the code.
+
+
+Running the test suite
+----------------------
+
+The easiest way to run all the tests is to go to librsvg's toplevel
+directory and run "make check".  This will run both the small unit
+tests and the black box tests in this librsvg/tests directory.
+
+If you want to run just the black box tests, go into this
+librsvg/tests directory and run "make check".
+
+Those commands will yield exit code 0 if all the tests pass, or
+nonzero if some tests fail.
+
+Running "make check" will produce a test/test-suite.log file.  You can
+see this file for the details of failed tests.
+
+Additionally, all three sets of black box tests (crash, styles,
+rsvg-test) will produce a test report in a text file.  In the tests
+directory, you can see crash.log, styles.log, rsvg-test.log,
+respectively.
+
+
+Tests and test fixtures
+-----------------------
+
+# Image-based reference tests for rsvg-test.c
+
+These will load, parse, and render an SVG, and compare the results
+against a reference PNG image.
+
+Each image-based reference test uses two files: foo.svg and
+foo-ref.png.  The test harness will render foo.svg and compare the
+results to foo-ref.png.  Currently we assume a pixel-perfect match.
+If there are differences in the output, the test will fail; see
+"Examining failed tests" below.
+
+These files can go anywhere under the fixtures/reftests
+directory; the "rsvg-test" program will recursively look inside
+fixtures/reftests for all SVG files, render them, and compare them to
+the -ref.png reference images.
+
+As of 2016/Nov/03 we have an informal organization of these files:
+
+* fixtures/reftests/*.svg - Tests for special situations
+  that arose during development.
+
+* fixtures/reftests/bugs/*.svg - Tests for particular bug numbers.
+  Please use the bug number from Bugzilla, like 123456.svg, and the
+  corresponding 123456-ref.png for the known-good reference image.
+
+* fixtures/reftests/svg1.1 - Tests from the W3C's SVG test suite.
+  These are supposed to test all of SVG's features; we'll add them one
+  by one as librsvg starts implementing the features.
+
+
+# Crash tests for crash.c
+
+These load and parse an SVG, and ensure that there are no errors in
+the process.  Note that this does *not* render the images.
+
+The SVG images live in the fixtures/crash directory.  The "crash"
+program will look recursively look inside fixtures/crash for all SVG
+files, load them, and ensure that no GError was produced while loading
+each file.
+
+
+# Style tests for styles.c
+
+These load and parse an SVG, ask librsvg to fetch an SVG object by its
+id, and ensure that the object has certain style properties with
+particular values.
+
+
+Examining failed reference tests
+--------------------------------
+
+Let's say you run "make check" and see that one of the tests fails.
+For example, rsvg-test.log may have lines that look like
+
+```
+# Storing test result image at /tmp/paths-data-18-f-out.png
+# 6798 pixels differ (with maximum difference of 255) from reference image
+
+# Storing test result image at /tmp/paths-data-18-f-diff.png
+not ok 29 /rsvg-test/reftests/svg1.1/paths-data-18-f.svg
+FAIL: rsvg-test 29 /rsvg-test/reftests/svg1.1/paths-data-18-f.svg
+```
+
+This means that the test named
+"/rsvg-test/reftests/svg1.1/paths-data-18-f.svg" failed:  those are
+autogenerated test names from GTest.  In this case, it means that the
+test file fixtures/reftests/svg1.1/paths-data-18-f.svg got rendered,
+and produced incorrect output when compared to
+fixtures/reftests/svg1.1/paths-data-18-f-out.png.
+
+When a test fails, rsvg-test creates two images:
+
+```
+/tmp/foo-out.png
+/tmp/foo-diff.png
+```
+
+In this case, foo-out.png is the actual rendered output, which is presumed to
+be incorrect, since it differs from the foo-ref.png reference image.
+The foo-diff.png is a "visual diff" that you can see in an image
+viewer; pixels that differ are highlighted.
+
+It is up to you to decide what to do next:
+
+* If the foo-out.png image looks correct, and the only difference with
+  respect to the foo-ref.png reference image is that antialiased edges
+  look different, or font rendering is slightly different due to
+  system-specific changes, you can just regenerate the test image.
+  See "Regenerating reference images" below.
+
+* If the foo-out.png image is obviously wrong when compared to the
+  foo-ref.png reference, you can file a bug in bugzilla.gnome.org.  You can wait
+  until someone fixes it, or try to fix the bug yourself!
+
+* Any other situation of course deserves attention.  Feel free to ask
+  the maintainers about it; even if you figure out the problem
+  yourself, a failed test almost always indicates a problem that is
+  not just on your end.
+
+
+Regenerating reference images
+-----------------------------
+
+Let's continue with the example above, where the test
+/rsvg-test/reftests/svg1.1/paths-data-18-f.svg failed.  Let's say you
+fix the bug, or determine that the output image is in fact correct,
+and just differs from the reference image due to antialiasing
+artifacts.  In this case, you'll want to regenerate the reference
+image so the test passes again.
+
+If you want to regenerate the reference image
+fixtures/reftests/foo/bar.png, you can run
+
+```
+rsvg-convert -o fixtures/reftests/foo/bar.png fixtures/reftests/foo/bar.svg
+```
+
+This is just the normal rsvg-convert program doing its job; it will
+just render the SVG image and output it to the specified PNG file.
+
+You can then run "make check" again and ensure that the tests pass.
diff --git a/tests/rsvg-test.c b/tests/rsvg-test.c
index 4ea854b..0f39f66 100644
--- a/tests/rsvg-test.c
+++ b/tests/rsvg-test.c
@@ -307,7 +307,7 @@ main (int argc, char **argv)
 
         base = g_file_new_for_path (test_utils_get_test_data_path ());
         tests = g_file_get_child (base, "reftests");
-        test_utils_add_test_for_all_files ("/rsvg/reftest", tests, tests, rsvg_cairo_check, 
is_svg_or_subdir);
+        test_utils_add_test_for_all_files ("/rsvg-test/reftests", tests, tests, rsvg_cairo_check, 
is_svg_or_subdir);
         g_object_unref (tests);
         g_object_unref (base);
     } else {
@@ -316,7 +316,7 @@ main (int argc, char **argv)
         for (i = 1; i < argc; i++) {
             GFile *file = g_file_new_for_commandline_arg (argv[i]);
 
-            test_utils_add_test_for_all_files ("/rsvg/reftest", NULL, file, rsvg_cairo_check, 
is_svg_or_subdir);
+            test_utils_add_test_for_all_files ("/rsvg-test/reftests", NULL, file, rsvg_cairo_check, 
is_svg_or_subdir);
 
             g_object_unref (file);
         }