testing/web-platform/tests/docs/writing-tests/reftests.md

   1 # Reftests
   2
   3 Reftests are one of the primary tools for testing things relating to
   4 rendering; they are made up of the test and one or more other pages
   5 ("references") with assertions as to whether they render identically
   6 or not.
   7
   8 ## How to Run Reftests
   9
  10 Reftests can be run manually simply by opening the test and the
  11 reference file in multiple windows or tabs and flipping between the
  12 two. In automation the comparison is done in an automated fashion,
  13 which can lead to differences hard for the human eye to notice to
  14 cause the test to fail.
  15
  16 ## Components of a Reftest
  17
  18 In the simplest case, a reftest consists of a pair of files called the
  19 *test* and the *reference*.
  20
  21 The *test* file is the one that makes use of the technology being
  22 tested. It also contains a `link` element with `rel="match"` or
  23 `rel="mismatch"` and `href` attribute pointing to the *reference*
  24 file, e.g. `<link rel=match href=references/green-box-ref.html>`. A
  25 `match` test only passes if the two files render pixel-for-pixel
  26 identically within a 800x600 window *including* scroll-bars if
  27 present; a `mismatch` test only passes if they *don't* render
  28 identically.
  29
  30 The *reference* file is typically written to be as simple as possible,
  31 and does not use the technology under test. It is desirable that the
  32 reference be rendered correctly even in UAs with relatively poor
  33 support for CSS and no support for the technology under test.
  34
  35 ## Writing a Good Reftest
  36
  37 In general the files used in a reftest should follow
  38 the [general guidelines][] and
  39 the [rendering test guidelines][rendering]. They should also be
  40 self-describing, to allow a human to determine whether the the
  41 rendering is as expected.
  42
  43 References can be shared between tests; this is strongly encouraged as
  44 it makes it easier to tell at a glance whether a test passes (through
  45 familiarity) and enables some optimizations in automated test
  46 runners. Shared references are typically placed in `references`
  47 directories, either alongside the tests they are expected to be useful
  48 for or at the top level if expected to be generally applicable (e.g.,
  49 many layout tests can be written such that the correct rendering is a
  50 100x100 green square!). For references that are applicable only to a
  51 single test, it is recommended to use the test name with a suffix of
  52 `-ref` as their filename; e.g., `test.html` would have `test-ref.html`
  53 as a reference.
  54
  55 ## Complex Pass Conditions
  56
  57 Sometimes it is desirable for a file to match multiple references or,
  58 in rare cases, to allow it to match more than one possible reference.
  59
  60 References can have links to other references (through the same `link`
  61 element relation), and in this case for the test to pass the test must
  62 render identically (assuming a `match` relation) to the reference, and
  63 the reference must render identically to its reference (again,
  64 assuming a `match` relation). Note that this can continue indefinitely
  65 to require tests to match an arbitrary number of references; also that
  66 `match` is used here purely for explanatory reasons: both `match` and
  67 `mismatch` can be used (and mixed on one sequence of references). This
  68 can be thought of as an AND operator!
  69
  70 Similarly, multiple references can be linked from a single file to
  71 implement alternates and allow multiple renderings. In this case, the
  72 file passes if it matches one of the references provided (and that
  73 reference likewise matches any references, etc.). This can be thought
  74 of as an OR operator!
  75
  76 These two techniques can be combined to build up arbitrarily complex
  77 pass conditions with boolean logic. For example, consider when:
  78
  79  * `a.html` has `<link rel=match href=b.html>` and `<link rel=match
  80 href=c.html>`,
  81  * `b.html` has `<link rel=match href=b1.html>`, and
  82  * `c.html` has `<link rel=mismatch href=c1.html>`.
  83
  84 Or, graphically:
  85
  86 <img src="../_static/reftest_graph_example.svg"
  87      alt="diagram of the above reftest graph as a directed graph">
  88
  89 In this case, to pass we must either have `a.html`, `b.html` and
  90 `b1.html` all rendering identically, or `a.html` and `c.html`
  91 rendering identically with `c1.html` rendering differently. (These
  92 are, in terms of the graph, all the paths from the source nodes to
  93 leaf nodes.)
  94
  95 ## Controlling When Comparison Occurs
  96
  97 By default reftest screenshots are taken after the `load` event has
  98 fired, and web fonts (if any) are loaded. In some cases it is
  99 necessary to delay the screenshot later than this, for example because
 100 some DOM manipulation is required to set up the desired test
 101 conditions. To enable this, the test may have a `class="reftest-wait"`
 102 attribute specified on the root element. This will cause the
 103 screenshot to be delayed until the `load` event has fired and the
 104 `reftest-wait` class has been removed from the root element. Note that
 105 in neither case is exact timing of the screenshot guaranteed: it is
 106 only guaranteed to be after those events.
 107
 108 ## Fuzzy Matching
 109
 110 In some situations a test may have subtle differences in rendering
 111 compared to the reference due to, e.g., anti-aliasing. To allow for
 112 these small differences, we allow tests to specify a fuzziness
 113 characterised by two parameters, both of which must be specified:
 114
 115  * A maximum difference in the per-channel color value for any pixel.
 116  * A number of total pixels that may be different.
 117
 118 The maximum difference in the per pixel color value is formally
 119 defined as follows: let <code>T<sub>x,y,c</sub></code> be the value of
 120 colour channel `c` at pixel coordinates `x`, `y` in the test image and
 121 <code>R<sub>x,y,c</sub></code> be the corresponding value in the
 122 reference image, and let <code>width</code> and <code>height</code> be
 123 the dimensions of the image in pixels. Then <code>maxDifference =
 124 max<sub>x=[0,width) y=[0,height), c={r,g,b}</sub>(|T<sub>x,y,c</sub> -
 125 R<sub>x,y,c</sub>|)</code>.
 126
 127 To specify the fuzziness in the test file one may add a `<meta
 128 name=fuzzy>` element (or, in the case of more complex tests, to any
 129 page containing the `<link rel=[mis]match>` elements). In the simplest
 130 case this has a `content` attribute containing the parameters above,
 131 separated by a colon e.g.
 132
 133 ```
 134 <meta name=fuzzy content="maxDifference=15;totalPixels=300">
 135 ```
 136
 137 would allow for a  difference of exactly 15 / 255 on any color channel
 138 and 300 exactly pixels total difference. The argument names are optional
 139 and may be elided; the above is the same as:
 140
 141 ```
 142 <meta name=fuzzy content="15;300">
 143 ```
 144
 145 The values may also be given as ranges e.g.
 146
 147 ```
 148 <meta name=fuzzy content="maxDifference=10-15;totalPixels=200-300">
 149 ```
 150
 151 or
 152
 153 ```
 154 <meta name=fuzzy content="10-15;200-300">
 155 ```
 156
 157 In this case the maximum pixel difference must be in the range
 158 `10-15` and the total number of different pixels must be in the range
 159 `200-300`.
 160
 161 In cases where a single test has multiple possible refs and the
 162 fuzziness is not the same for all refs, a ref may be specified by
 163 prefixing the `content` value with the relative url for the ref e.g.
 164
 165 ```
 166 <meta name=fuzzy content="option1-ref.html:10-15;200-300">
 167 ```
 168
 169 One meta element is required per reference requiring a unique
 170 fuzziness value, but any unprefixed value will automatically be
 171 applied to any ref that doesn't have a more specific value.
 172
 173 ## Limitations
 174
 175 In some cases, a test cannot be a reftest. For example, there is no
 176 way to create a reference for underlining, since the position and
 177 thickness of the underline depends on the UA, the font, and/or the
 178 platform. However, once it's established that underlining an inline
 179 element works, it's possible to construct a reftest for underlining
 180 a block element, by constructing a reference using underlines on a
 181 ```<span>``` that wraps all the content inside the block.
 182
 183 ## Example Reftests
 184
 185 This example follows the recommended approach in being a
 186 self-describing test as it has a simple statement on the page
 187 describing how it should render to pass the tests.
 188
 189 ### Test File
 190
 191 This test verifies that a right-to-left rendering of **SAW** within a
 192 ```<bdo>``` element displays as **WAS**.
 193
 194 ```html
 195 <!DOCTYPE html>
 196 <meta charset="utf-8">
 197 <title>BDO element dir=rtl</title>
 198 <link rel="help" href="https://html.spec.whatwg.org/#the-bdo-element">
 199 <meta name="assert" content="BDO element's DIR content attribute renders corrently given value of 'rtl'.">
 200 <link rel="match" href="test-bdo-001.html">
 201 <p>Pass if you see WAS displayed below.</p>
 202 <bdo dir="rtl">SAW</bdo>
 203 ```
 204
 205 ### Reference File
 206
 207 The reference file must look exactly like the test file,
 208 except that the code behind it is different.
 209
 210 * All metadata is removed.
 211 * The ```title``` need not match.
 212 * The markup that created the actual test data is
 213   different: here, the same effect is created with
 214   very mundane, dependable technology.
 215
 216 ```html
 217 <!DOCTYPE html>
 218 <meta charset="utf-8">
 219 <title>HTML Reference File</title>
 220 <p>Pass if you see WAS displayed below.</p>
 221 <p>WAS</p>
 222 ```
 223
 224 [general guidelines]: general-guidelines
 225 [rendering]: rendering