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