test/README

   1 Regression test suite for cairo.
   2
   3 How to use cairo's test suite
   4 =============================
   5 Using this test should be as simple as running:
   6
   7         make test
   8
   9 assuming that the cairo distribution in the directory above has been
  10 configured and built. The test suite here goes through some effort to
  11 run against the locally compiled library rather than any installed
  12 version, but those efforts may fall short depending on the level of your
  13 libtool madness.
  14
  15 The results of the test suite run are summarized in an index.html
  16 file, which, when viewed in a web browser makes it quite easy to
  17 visually see any failed renderings alongside the corresponding
  18 reference image, (and a diff image as well).
  19
  20 The test suite needs to be run before any code is committed and before
  21 any release. See below for hints and rules governing the use of the suite.
  22
  23 The test suite is built as a single binary, which allows you to choose
  24 individual or categories of tests to run. For example, if you want to
  25 run all text related tests you can use:
  26     ./cairo-test-suite text
  27 Or if you want to check the current status of known failures:
  28     ./cairo-test-suite XFAIL
  29 Or to run a subset of tests, use the -k option to run only the tests
  30 that include the given keyword:
  31     ./cairo-test-suite -k downscale
  32 The binary also permits controlling which backend is used via the
  33 CAIRO_TEST_TARGET environment variable, so for instance:
  34     CAIRO_TEST_TARGET=gl ./cairo-test-suite -k blur
  35 This binary should be backwards-compatible with all library versions,
  36 allowing you to compare current versus past behaviour for any test.
  37
  38 Tailoring tests running
  39 -----------------------
  40 There are some mechanisms to limit the tests run during "make test".
  41 These come very handy when doing development, but should not be used
  42 to circumvent the "pass" requirements listed below.
  43
  44 make's TARGETS environment variable can be used to limit the backends when
  45 running the tests. It should contain a (space-, comma-separated) list of
  46 backends. CAIRO_TESTS environment variable, which is a comma-, space-seperated
  47 lists, can be used to limit the tests run.
  48 For example:
  49
  50   CAIRO_TESTS="zero-alpha" make test TARGETS=image,ps
  51
  52 make's FORMAT variable can also be used to limit the content formats when
  53 running the tests. It should contain a (space-, comma-separated) list of
  54 content formats to test.
  55 For example:
  56
  57   CAIRO_TESTS="zero-alpha" make test TARGETS=image,ps FORMAT="rgb,rgba"
  58
  59 Another very handy mechanism when trying to fix bugs is:
  60
  61   make retest
  62
  63 This will re-run the test suite, but only on tests that failed on the
  64 last run. So this is a much faster way of checking if changes actually
  65 fix bugs rather than running the entire test suite again.
  66
  67 The test suite first compares the output from the current run against the
  68 previous in order to skip more expensive image comparisons . If you think
  69 this is interfering with the results, you can clear the cached results using:
  70
  71   make clean-caches
  72
  73 Running tests under modified environments or tools
  74 -------------------------------------------------
  75 To run tests under a tool like gdb, one can use the run target and
  76 the TOOL variable.  For example:
  77
  78   CAIRO_TESTS=user-font make run TOOL=gdb TARGETS=pdf
  79
  80 If you want to run under valgrind, there is a specific target for that
  81 that also sets a bunch of useful valgrind options.  Try:
  82
  83   CAIRO_TESTS=user-font make check-valgrind
  84
  85 You can run tests under a modified environment you can use the ENV
  86 make variable.  However, that environment will also affect the libtool
  87 wrapper of the tests.  To only affect the actual test binaries, pass
  88 such environment as TOOL:
  89
  90   CAIRO_TESTS=user-font make run TOOL="LD_PRELOAD=/path/to/something.so"
  91
  92 Getting the elusive zero failures
  93 ---------------------------------
  94 It's generally been very difficult to achieve a test run with zero
  95 failures. The difficulties stem from the various versions of the many
  96 libraries that the test suite depends on, (it depends on a lot more
  97 than cairo itself), as well as fonts and other system-specific
  98 settings. If your system differs significantly from the system on
  99 which the reference images were generated, then you will likely see
 100 the test suite reporting "failures", (even if cairo is working just
 101 fine).
 102
 103 We are constantly working to reduce the number of variables that need
 104 to be tweaked to get a clean run, (for example, by bundling fonts with
 105 the test suite itself), and also working to more carefully document
 106 the software configuration used to generate the reference images.
 107
 108 Here are some of the relevant details:
 109
 110   * Your system must have a copy of the DejaVu font, the sha1sum of
 111     the version used are listed in [...].  These are
 112       "DejaVu Sans" (DejaVuSans.ttf) [1cd336329f45f241002ded61893d91e3acd04436];
 113       "DejaVu Sans Mono" (DejaVuSansMono.ttf) [0458c0f0fb57f3eb8ced62f26fe7c5ed4e6a9a68];
 114       "DejaVu Serif" (DejaVuSerif.ttf) [93502d0d0445d1fe1c9f51e51b3e0169266346ce];
 115       [the DejaVu fonts can be installed from the ttf-dejavu 2.33-2 Debian package]
 116     and also
 117       "Nimbus Sans L" (n019003l.pfb)
 118       [which can be found in the gsfonts Debian package].
 119
 120   * Currently, you must be using a build of cairo using freetype
 121     (cairo-ft) as the default font backend. Otherwise all tests
 122     involving text are likely to fail.
 123
 124   * To test the pdf backend, you will want the very latest version of
 125     poppler as made available via git:
 126
 127         git clone git://anongit.freedesktop.org/git/poppler/poppler
 128
 129     As of this writing, no released version of poppler contains all
 130     the fixes you will need to avoid false negatives from the test
 131     suite.
 132
 133   * To test the ps backend, you will need ghostscript version 9.04.
 134
 135   * Testing the xlib backend is problematic since many X server
 136     drivers have bugs that are exercised by the test suite. (Or, if
 137     not actual bugs, differ slightly in their output in such a way
 138     that the test suite will report errors.) This can be quite handy
 139     if you want to debug an X server driver, but since most people
 140     don't want to do that, another option is to run against a headless
 141     X server that uses only software for all rendering. One such X
 142     server is Xvfb which can be started like this:
 143
 144         Xvfb -screen 0 1680x1024x24 -ac -nolisten tcp :2
 145
 146     after which the test suite can be run against it like so:
 147
 148         DISPLAY=:2 make test
 149
 150     We have been using Xvfb for testing cairo releases and ensuring
 151     that all tests behave as expected with this X server.
 152
 153 What if I can't make my system match?
 154 -------------------------------------
 155 For one reason or another, you may be unable to get a clean run of the
 156 test suite even if cairo is working properly, (for example, you might
 157 be on a system without freetype). In this case, it's still useful to
 158 be able to determine if code changes you make to cairo result in any
 159 regressions to the test suite. But it's hard to notice regressions if
 160 there are many failures both before and after your changes.
 161
 162 For this scenario, you can capture the output of a run of the test
 163 suite before your changes, and then use the CAIRO_REF_DIR environment
 164 variable to use that output as the reference images for a run after
 165 your changes. The process looks like this:
 166
 167         # Before code change there may be failures we don't care about
 168         make test
 169
 170         # Let's save those output images
 171         mkdir /some/directory/
 172         cp -r test/output /some/directory/
 173
 174         # hack, hack, hack
 175
 176         # Now to see if nothing changed:
 177         CAIRO_REF_DIR=/some/directory/ make test
 178
 179 Best practices for cairo developers
 180 ===================================
 181 If we all follow the guidelines below, then both the test suite and
 182 cairo itself will stay much healthier, and we'll all have a lot more
 183 fun hacking on cairo.
 184
 185 Before committing
 186 -----------------
 187 All tests should return a result of PASS or XFAIL. The XFAIL results
 188 indicate known bugs. The final message should be one of the following:
 189
 190         All XX tests behaved as expected (YY expected failures)
 191         All XX tests passed
 192
 193 If any tests have a status of FAIL, then the new code has caused a
 194 regression error which should be fixed before the code is committed.
 195
 196 When a new bug is found
 197 -----------------------
 198 A new test case should be added by imitating the style of an existing
 199 test. This means adding the following files:
 200
 201         new-bug.c
 202         reference/new-bug.ref.png
 203         reference/new-bug.xfail.png
 204
 205 Where new-bug.c is a minimal program to demonstrate the bug, following
 206 the style of existing tests. The new-bug.ref.png image should contain
 207 the desired result of new-bug.c if the bug were fixed while
 208 new-bug.xfail.png contains the current results of the test.
 209
 210 Makefile.sources should be edited by adding new-bug.c to test_sources.
 211 And last but not least, don't forget to "git add" the new files.
 212
 213 When a new feature is added
 214 ---------------------------
 215 It's important for the regression suite to keep pace with development
 216 of the library. So a new test should be added for each new feature.
 217 The work involved is similar the work described above for new bugs.
 218 The only distinction is that the test is expected to pass so it
 219 should not need a new-bug.xfail.png file.
 220
 221 While working on a test
 222 -----------------------
 223 Before a bugfix or feature is ready, it may be useful to compare
 224 output from different builds. For convenience, you can set
 225 CAIRO_REF_DIR to point at a previous test directory, relative
 226 to the current test directory, and any previous output will be
 227 used by preference as reference images.
 228
 229 When a bug is fixed
 230 -------------------
 231 The fix should be verified by running the test suite which should
 232 result in an "unexpected pass" for the test of interest. Rejoice as
 233 appropriate, then remove the relevant xfail.png file from git.
 234
 235 Before releasing
 236 ----------------
 237 All tests should return a result of PASS for all supported (those enabled by
 238 default) backends, meaning all known bugs are fixed, resulting in the happy
 239 message:
 240
 241         All XX tests passed
 242
 243 Some notes on limitations in poppler
 244 ====================================
 245 One of the difficulties of our current test infrastructure is that we
 246 rely on external tools to convert cairo's vector output (PDF,
 247 PostScript, and SVG), into an image that can be used for the image
 248 comparison. This means that any bugs in that conversion tool will
 249 result in false negatives in the test suite.
 250
 251 We've identified several such bugs in the poppler library which is
 252 used to convert PDF to an image. This is particularly discouraging
 253 because 1) poppler is free software that will be used by *many* cairo
 254 users, and 2) poppler calls into cairo for its rendering so it should
 255 be able to do a 100% faithful conversion.
 256
 257 So we have an interest in ensuring that these poppler bugs get fixed
 258 sooner rather than later. As such, we're trying to be good citizens by
 259 reporting all such poppler bugs that we identify to the poppler
 260 bugzilla. Here's a tracking bug explaining the situation:
 261
 262         Poppler does not yet handle everything in the cairo test suite
 263         https://bugs.freedesktop.org/show_bug.cgi?id=12143
 264
 265 Here's the rule: If a cairo-pdf test reports a failure, but viewing
 266 the resulting PDF file with acroread suggests that the PDF itself is
 267 correct, then there's likely a bug in poppler. In this case, we can
 268 simply report the poppler bug, (making it block 12143 above), post the
 269 PDF result from the test suite, and list the bug in this file. Once
 270 we've done this, we can capture poppler's buggy output as a
 271 pdf-specific reference image (as reference/*.xfail.png) so that the
 272 test suite will regard the test as passing, (and we'll ensure there
 273 is no regression).
 274
 275 Once the poppler bug gets fixed, the test suite will start reporting a
 276 false negative again, and this will be easy to fix by simply removing
 277 the pdf-specific reference image.
 278
 279 Here are the reported poppler bugs and the tests they affect:
 280
 281 Poppler doesn't correctly handle gradients with transparency
 282 https://bugs.freedesktop.org/show_bug.cgi?id=12144
 283 --------------------------------------------------
 284 fill-alpha-pattern
 285 gradient-alpha
 286 gradient-constant-alpha
 287 linear-gradient
 288 linear-gradient-reflect
 289 radial-gradient
 290 trap-clip
 291
 292 Poppler should paint images with CAIRO_EXTEND_PAD
 293 https://bugs.freedesktop.org/show_bug.cgi?id=14578
 294 --------------------------------------------------
 295 paint-source-alpha
 296 paint-with-alpha
 297 rotate-image-surface-paint
 298 scale-source-surface-paint
 299
 300 Incorrect clipping of group object (regression?)
 301 https://bugs.freedesktop.org/show_bug.cgi?id=14580
 302 --------------------------------------------------
 303 push-group
 304
 305 spurious horizontal stripes in color gradients
 306 https://bugs.freedesktop.org/show_bug.cgi?id=10942
 307 --------------------------------------------------
 308 smask
 309 smask-fill
 310 smask-image-mask
 311 smask-mask
 312 smask-paint
 313 smask-stroke
 314 smask-text
 315
 316 Ghostscript does not correctly render small miters
 317 http://bugs.ghostscript.com/show_bug.cgi?id=690098
 318 --------------------------------------------------
 319 miter-precision