1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/layout/tools/reftest/README.txt Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,571 @@
1.4 +Layout Engine Visual Tests (reftest)
1.5 +L. David Baron <dbaron@dbaron.org>, Mozilla Corporation
1.6 +July 19, 2006
1.7 +
1.8 +This code is designed to run tests of Mozilla's layout engine. These
1.9 +tests consist of an HTML (or other format) file along with a reference
1.10 +in the same format. The tests are run based on a manifest file, and for
1.11 +each test, PASS or FAIL is reported, and UNEXPECTED is reported if the
1.12 +result (PASS or FAIL) was not the expected result noted in the manifest.
1.13 +
1.14 +Images of the display of both tests are captured, and most test types
1.15 +involve comparing these images (e.g., test types == or !=) to determine
1.16 +whether the test passed. The captures of the tests are taken in a
1.17 +viewport that is 800 pixels wide and 1000 pixels tall, so any content
1.18 +outside that area will be ignored (except for any scrollbars that are
1.19 +displayed). Ideally, however, tests should be written so that they fit
1.20 +within 600x600, since we may in the future want to switch to 600x600 to
1.21 +match http://lists.w3.org/Archives/Public/www-style/2012Sep/0562.html .
1.22 +
1.23 +Why this way?
1.24 +=============
1.25 +
1.26 +Writing HTML tests where the reference rendering is also in HTML is
1.27 +harder than simply writing bits of HTML that can be regression-tested by
1.28 +comparing the rendering of an older build to that of a newer build
1.29 +(perhaps using stored reference images from the older build). However,
1.30 +comparing across time has major disadvantages:
1.31 +
1.32 + * Comparisons across time either require two runs for every test, or
1.33 + they require stored reference images appropriate for the platform and
1.34 + configuration (often limiting testing to a very specific
1.35 + configuration).
1.36 +
1.37 + * Comparisons across time may fail due to expected changes, for
1.38 + example, changes in the default style sheet for HTML, changes in the
1.39 + appearance of form controls, or changes in default preferences like
1.40 + default font size or default colors.
1.41 +
1.42 +Using tests for which the pass criteria were explicitly chosen allows
1.43 +running tests at any time to see whether they still pass.
1.44 +
1.45 +Manifest Format
1.46 +===============
1.47 +
1.48 +The test manifest format is a plain text file. A line starting with a
1.49 +"#" is a comment. Lines may be commented using whitespace followed by
1.50 +a "#" and the comment. Each non-blank line (after removal of comments)
1.51 +must be one of the following:
1.52 +
1.53 +1. Inclusion of another manifest
1.54 +
1.55 + <failure-type>* include <relative_path>
1.56 +
1.57 + <failure-type> is the same as listed below for a test item. As for
1.58 + test items, multiple failure types listed on the same line are
1.59 + combined by using the last matching failure type listed. However,
1.60 + the failure type on a manifest is combined with the failure type on
1.61 + the test (or on a nested manifest) with the rule that the last in the
1.62 + following list wins: fails, random, skip. (In other words, skip
1.63 + always wins, and random beats fails.)
1.64 +
1.65 +2. A test item
1.66 +
1.67 + [ <failure-type> | <preference> ]* [<http>] <type> <url> <url_ref>
1.68 +
1.69 + where
1.70 +
1.71 + a. <failure-type> (optional) is one of the following:
1.72 +
1.73 + fails The test passes if the images of the two renderings DO NOT
1.74 + meet the conditions specified in the <type>.
1.75 +
1.76 + fails-if(condition) If the condition is met, the test passes if the
1.77 + images of the two renderings DO NOT meet the
1.78 + conditions of <type>. If the condition is not met,
1.79 + the test passes if the conditions of <type> are met.
1.80 +
1.81 + needs-focus The test fails or times out if the reftest window is not
1.82 + focused.
1.83 +
1.84 + random The results of the test are random and therefore not to be
1.85 + considered in the output.
1.86 +
1.87 + random-if(condition) The results of the test are random if a given
1.88 + condition is met.
1.89 +
1.90 + silentfail This test may fail silently, and if that happens it should
1.91 + count as if the test passed. This is useful for cases where
1.92 + silent failure is the intended behavior (for example, in
1.93 + an out of memory situation in JavaScript, we stop running
1.94 + the script silently and immediately, in hopes of reclaiming
1.95 + enough memory to keep the browser functioning).
1.96 +
1.97 + silentfail-if(condition) This test may fail silently if the condition
1.98 + is met.
1.99 +
1.100 + skip This test should not be run. This is useful when a test fails in a
1.101 + catastrophic way, such as crashing or hanging the browser. Using
1.102 + 'skip' is preferred to simply commenting out the test because we
1.103 + want to report the test failure at the end of the test run.
1.104 +
1.105 + skip-if(condition) If the condition is met, the test is not run. This is
1.106 + useful if, for example, the test crashes only on a
1.107 + particular platform (i.e. it allows us to get test
1.108 + coverage on the other platforms).
1.109 +
1.110 + slow The test may take a long time to run, so run it if slow tests are
1.111 + either enabled or not disabled (test manifest interpreters may
1.112 + choose whether or not to run such tests by default).
1.113 +
1.114 + slow-if(condition) If the condition is met, the test is treated as if
1.115 + 'slow' had been specified. This is useful for tests
1.116 + which are slow only on particular platforms (e.g. a
1.117 + test which exercised out-of-memory behavior might be
1.118 + fast on a 32-bit system but inordinately slow on a
1.119 + 64-bit system).
1.120 +
1.121 + fuzzy(maxDiff, diffCount)
1.122 + This allows a test to pass if the pixel value differences are <=
1.123 + maxDiff and the total number of different pixels is <= diffCount.
1.124 + It can also be used with '!=' to ensure that the difference is
1.125 + greater than maxDiff.
1.126 +
1.127 + fuzzy-if(condition, maxDiff, diffCount)
1.128 + If the condition is met, the test is treated as if 'fuzzy' had been
1.129 + specified. This is useful if there are differences on particular
1.130 + platforms.
1.131 +
1.132 + require-or(cond1&&cond2&&...,fallback)
1.133 + Require some particular setup be performed or environmental
1.134 + condition(s) made true (eg setting debug mode) before the test
1.135 + is run. If any condition is unknown, unimplemented, or fails,
1.136 + revert to the fallback failure-type.
1.137 + Example: require-or(debugMode,skip)
1.138 +
1.139 + asserts(count)
1.140 + Loading the test and reference is known to assert exactly
1.141 + count times.
1.142 + NOTE: An asserts() notation with a non-zero count or maxCount
1.143 + suppresses use of a cached canvas for the test with the
1.144 + annotation. However, if later occurrences of the same test
1.145 + are not annotated, they will use the cached canvas
1.146 + (potentially from the load that asserted). This allows
1.147 + repeated use of the same test or reference to be annotated
1.148 + correctly (which may be particularly useful when the uses are
1.149 + in different subdirectories that can be tested independently),
1.150 + but does not force them to be, nor does it force suppression
1.151 + of caching for a common reference when it is the test that
1.152 + asserts.
1.153 +
1.154 + asserts(minCount-maxCount)
1.155 + Loading the test and reference is known to assert between
1.156 + minCount and maxCount times, inclusive.
1.157 + NOTE: See above regarding canvas caching.
1.158 +
1.159 + asserts-if(condition,count)
1.160 + asserts-if(condition,minCount-maxCount)
1.161 + Same as above, but only if condition is true.
1.162 +
1.163 + Conditions are JavaScript expressions *without spaces* in them.
1.164 + They are evaluated in a sandbox in which a limited set of
1.165 + variables are defined. See the BuildConditionSandbox function in
1.166 + layout/tools/reftest.js for details.
1.167 +
1.168 + Examples of using conditions:
1.169 + fails-if(winWidget) == test reference
1.170 + asserts-if(cocoaWidget,2) load crashtest
1.171 +
1.172 + b. <preference> (optional) is a string of the form
1.173 +
1.174 + pref(<name>,<value>)
1.175 + test-pref(<name>,<value>)
1.176 + ref-pref(<name>,<value>)
1.177 +
1.178 + where <name> is the name of a preference setting, as seen in
1.179 + about:config, and <value> is the value to which this preference should
1.180 + be set. <value> may be a boolean (true/false), an integer, or a
1.181 + quoted string *without spaces*, according to the type of the preference.
1.182 +
1.183 + The preference will be set to the specified value prior to
1.184 + rendering the test and/or reference canvases (pref() applies to
1.185 + both, test-pref() only to the test, and ref-pref() only to the
1.186 + reference), and will be restored afterwards so that following
1.187 + tests are not affected. Note that this feature is only useful for
1.188 + "live" preferences that take effect immediately, without requiring
1.189 + a browser restart.
1.190 +
1.191 + c. <http>, if present, is one of the strings (sans quotes) "HTTP" or
1.192 + "HTTP(..)" or "HTTP(../..)" or "HTTP(../../..)", etc. , indicating that
1.193 + the test should be run over an HTTP server because it requires certain
1.194 + HTTP headers or a particular HTTP status. (Don't use this if your test
1.195 + doesn't require this functionality, because it unnecessarily slows down
1.196 + the test.)
1.197 +
1.198 + With "HTTP", HTTP tests have the restriction that any resource an HTTP
1.199 + test accesses must be accessed using a relative URL, and the test and
1.200 + the resource must be within the directory containing the reftest
1.201 + manifest that describes the test (or within a descendant directory).
1.202 + The variants "HTTP(..)", etc., can be used to relax this restriction by
1.203 + allowing resources in the parent directory, etc.
1.204 +
1.205 + To modify the HTTP status or headers of a resource named FOO, create a
1.206 + sibling file named FOO^headers^ with the following contents:
1.207 +
1.208 + [<http-status>]
1.209 + <http-header>*
1.210 +
1.211 + <http-status> A line of the form "HTTP ###[ <description>]", where
1.212 + ### indicates the desired HTTP status and <description>
1.213 + indicates a desired HTTP status description, if any.
1.214 + If this line is omitted, the default is "HTTP 200 OK".
1.215 + <http-header> A line in standard HTTP header line format, i.e.
1.216 + "Field-Name: field-value". You may not repeat the use
1.217 + of a Field-Name and must coalesce such headers together,
1.218 + and each header must be specified on a single line, but
1.219 + otherwise the format exactly matches that from HTTP
1.220 + itself.
1.221 +
1.222 + HTTP tests may also incorporate SJS files. SJS files provide similar
1.223 + functionality to CGI scripts, in that the response they produce can be
1.224 + dependent on properties of the incoming request. Currently these
1.225 + properties are restricted to method type and headers, but eventually
1.226 + it should be possible to examine data in the body of the request as
1.227 + well when computing the generated response. An SJS file is a JavaScript
1.228 + file with a .sjs extension which defines a global |handleRequest|
1.229 + function (called every time that file is loaded during reftests) in this
1.230 + format:
1.231 +
1.232 + function handleRequest(request, response)
1.233 + {
1.234 + response.setStatusLine(request.httpVersion, 200, "OK");
1.235 +
1.236 + // You *probably* want this, or else you'll get bitten if you run
1.237 + // reftest multiple times with the same profile.
1.238 + response.setHeader("Cache-Control", "no-cache");
1.239 +
1.240 + response.write("any ASCII data you want");
1.241 +
1.242 + var outputStream = response.bodyOutputStream;
1.243 + // ...anything else you want to do, synchronously...
1.244 + }
1.245 +
1.246 + For more details on exactly which functions and properties are available
1.247 + on request/response in handleRequest, see the nsIHttpRe(quest|sponse)
1.248 + definitions in <netwerk/test/httpserver/nsIHttpServer.idl>.
1.249 +
1.250 + d. <type> is one of the following:
1.251 +
1.252 + == The test passes if the images of the two renderings are the
1.253 + SAME.
1.254 + != The test passes if the images of the two renderings are
1.255 + DIFFERENT.
1.256 + load The test passes unconditionally if the page loads. url_ref
1.257 + must be omitted, and the test cannot be marked as fails or
1.258 + random. (Used to test for crashes, hangs, assertions, and
1.259 + leaks.)
1.260 + script The loaded page records the test's pass or failure status
1.261 + in a JavaScript data structure accessible through the following
1.262 + API.
1.263 +
1.264 + getTestCases() returns an array of test result objects
1.265 + representing the results of the tests performed by the page.
1.266 +
1.267 + Each test result object has two methods:
1.268 +
1.269 + testPassed() returns true if the test result object passed,
1.270 + otherwise it returns false.
1.271 +
1.272 + testDescription() returns a string describing the test
1.273 + result.
1.274 +
1.275 + url_ref must be omitted. The test may be marked as fails or
1.276 + random. (Used to test the JavaScript Engine.)
1.277 +
1.278 + e. <url> is either a relative file path or an absolute URL for the
1.279 + test page
1.280 +
1.281 + f. <url_ref> is either a relative file path or an absolute URL for
1.282 + the reference page
1.283 +
1.284 + The only difference between <url> and <url_ref> is that results of
1.285 + the test are reported using <url> only.
1.286 +
1.287 +3. Specification of a url prefix
1.288 +
1.289 + url-prefix <string>
1.290 +
1.291 + <string> will be prepended to relative <url> and <url_ref> for all following
1.292 + test items in the manifest.
1.293 +
1.294 + <string> will not be prepended to the relative path when including another
1.295 + manifest, e.g. include <relative_path>.
1.296 +
1.297 + <string> will not be prepended to any <url> or <url_ref> matching the pattern
1.298 + /^\w+:/. This will prevent the prefix from being applied to any absolute url
1.299 + containing a protocol such as data:, about:, or http:.
1.300 +
1.301 + While the typical use of url-prefix is expected to be as the first line of
1.302 + a manifest, it is legal to use it anywhere in a manifest. Subsequent uses
1.303 + of url-prefix overwrite any existing values.
1.304 +
1.305 +4. Specification of default preferences
1.306 +
1.307 + default-preferences <preference>*
1.308 +
1.309 + where <preference> is defined above.
1.310 +
1.311 + The <preference> settings will be used for all following test items in the
1.312 + manifest.
1.313 +
1.314 + If a test item includes its own preference settings, then they will override
1.315 + any settings for preferences of the same names that are set using
1.316 + default-preferences, just as later items within a line override earlier ones.
1.317 +
1.318 + A default-preferences line with no <preference> settings following it will
1.319 + reset the set of default preferences to be empty.
1.320 +
1.321 + As with url-prefix, default-preferences will often be used at the start of a
1.322 + manifest file so that it applies to all test items, but it is legal for
1.323 + default-preferences to appear anywhere in the manifest. A subsequent
1.324 + default-preferences will reset any previous default preference values and
1.325 + overwrite them with the specified <preference> values.
1.326 +
1.327 +This test manifest format could be used by other harnesses, such as ones
1.328 +that do not depend on XUL, or even ones testing other layout engines.
1.329 +
1.330 +Running Tests
1.331 +=============
1.332 +
1.333 +(If you're not using a DEBUG build, first set browser.dom.window.dump.enabled
1.334 +to true (in about:config, in the profile you'll be using to run the tests).
1.335 +Create the option as a new boolean if it doesn't exist already. If you skip
1.336 +this step you won't get any output in the terminal.)
1.337 +
1.338 +At some point in the future there will hopefully be a cleaner way to do
1.339 +this. For now, go to your object directory, and run (perhaps using
1.340 +MOZ_NO_REMOTE=1 or the -profile <directory> option)
1.341 +
1.342 +./firefox -reftest /path/to/srcdir/mozilla/layout/reftests/reftest.list > reftest.out
1.343 +
1.344 +and then search/grep reftest.out for "UNEXPECTED".
1.345 +
1.346 +There are two scripts provided to convert the reftest.out to HTML.
1.347 +clean-reftest-output.pl converts reftest.out into simple HTML, stripping
1.348 +lines from the log that aren't relevant. reftest-to-html.pl converts
1.349 +the output into html that makes it easier to visually check for
1.350 +failures.
1.351 +
1.352 +Testable Areas
1.353 +==============
1.354 +
1.355 +This framework is capable of testing many areas of the layout engine.
1.356 +It is particularly well-suited to testing dynamic change handling (by
1.357 +comparison to the static end-result as a reference) and incremental
1.358 +layout (comparison of a script-interrupted layout to one that was not).
1.359 +However, it is also possible to write tests for many other things that
1.360 +can be described in terms of equivalence, for example:
1.361 +
1.362 + * CSS cascading could be tested by comparing the result of a
1.363 + complicated set of style rules that makes a word green to <span
1.364 + style="color:green">word</span>.
1.365 +
1.366 + * <canvas> compositing operators could be tested by comparing the
1.367 + result of drawing using canvas to a block-level element with the
1.368 + desired color as a CSS background-color.
1.369 +
1.370 + * CSS counters could be tested by comparing the text output by counters
1.371 + with a page containing the text written out
1.372 +
1.373 + * complex margin collapsing could be tested by comparing the complex
1.374 + case to a case where the margin is written out, or where the margin
1.375 + space is created by an element with 'height' and transparent
1.376 + background
1.377 +
1.378 +When it is not possible to test by equivalence, it may be possible to
1.379 +test by non-equivalence. For example, testing justification in cases
1.380 +with more than two words, or more than three different words, is
1.381 +difficult. However, it is simple to test that justified text is at
1.382 +least displayed differently from left-, center-, or right-aligned text.
1.383 +
1.384 +Writing Tests
1.385 +=============
1.386 +
1.387 +When writing tests for this framework, it is important for the test to
1.388 +depend only on behaviors that are known to be correct and permanent.
1.389 +For example, tests should not depend on default font sizes, default
1.390 +margins of the body element, the default style sheet used for HTML, the
1.391 +default appearance of form controls, or anything else that can be
1.392 +avoided.
1.393 +
1.394 +In general, the best way to achieve this is to make the test and the
1.395 +reference identical in as many aspects as possible. For example:
1.396 +
1.397 + Good test markup:
1.398 + <div style="color:green"><table><tr><td><span>green
1.399 + </span></td></tr></table></div>
1.400 +
1.401 + Good reference markup:
1.402 + <div><table><tr><td><span style="color:green">green
1.403 + </span></td></tr></table></div>
1.404 +
1.405 + BAD reference markup:
1.406 + <!-- 3px matches the default cellspacing and cellpadding -->
1.407 + <div style="color:green; padding: 3px">green
1.408 + </div>
1.409 +
1.410 + BAD test markup:
1.411 + <!-- span doesn't change the positioning, so skip it -->
1.412 + <div style="color:green"><table><tr><td>green
1.413 + </td></tr></table></div>
1.414 +
1.415 +Asynchronous Tests: class="reftest-wait"
1.416 +========================================
1.417 +
1.418 +Normally reftest takes a snapshot of the given markup's rendering right
1.419 +after the load event fires for content. If your test needs to postpone
1.420 +the moment the snapshot is taken, it should make sure a class
1.421 +'reftest-wait' is on the root element by the moment the load event
1.422 +fires. The easiest way to do this is to put it in the markup, e.g.:
1.423 + <html class="reftest-wait">
1.424 +
1.425 +When your test is ready, you should remove this class from the root
1.426 +element, for example using this code:
1.427 + document.documentElement.className = "";
1.428 +
1.429 +
1.430 +Note that in layout tests it is often enough to trigger layout using
1.431 + document.body.offsetWidth // HTML example
1.432 +
1.433 +When possible, you should use this technique instead of making your
1.434 +test async.
1.435 +
1.436 +Invalidation Tests: MozReftestInvalidate Event
1.437 +==============================================
1.438 +
1.439 +When a test (or reference) uses reftest-wait, reftest tracks invalidation
1.440 +via MozAfterPaint and updates the test image in the same way that
1.441 +a regular window would be repainted. Therefore it is possible to test
1.442 +invalidation-related bugs by setting up initial content and then
1.443 +dynamically modifying it before removing reftest-wait. However, it is
1.444 +important to get the timing of these dynamic modifications right so that
1.445 +the test doesn't accidentally pass because a full repaint of the window
1.446 +was already pending. To help with this, reftest fires one MozReftestInvalidate
1.447 +event at the document root element for a reftest-wait test when it is safe to
1.448 +make changes that should test invalidation. The event bubbles up to the
1.449 +document and window so you can set listeners there too. For example,
1.450 +
1.451 +function doTest() {
1.452 + document.body.style.border = "";
1.453 + document.documentElement.removeAttribute('class');
1.454 +}
1.455 +document.addEventListener("MozReftestInvalidate", doTest, false);
1.456 +
1.457 +Painting Tests: class="reftest-no-paint"
1.458 +========================================
1.459 +
1.460 +If an element shouldn't be painted, set the class "reftest-no-paint" on it
1.461 +when doing an invalidation test. Causing a repaint in your
1.462 +MozReftestInvalidate handler (for example, by changing the body's background
1.463 +colour) will accurately test whether the element is painted.
1.464 +
1.465 +Snapshot The Whole Window: class="reftest-snapshot-all"
1.466 +=======================================================
1.467 +
1.468 +In a reftest-wait test, to disable testing of invalidation and force the final
1.469 +snapshot to be taken of the whole window, set the "reftest-snapshot-all"
1.470 +class on the root element.
1.471 +
1.472 +Zoom Tests: reftest-zoom="<float>"
1.473 +==================================
1.474 +
1.475 +When the root element of a test has a "reftest-zoom" attribute, that zoom
1.476 +factor is applied when rendering the test. The reftest document will be
1.477 +800 device pixels wide by 1000 device pixels high. The reftest harness assumes
1.478 +that the CSS pixel dimensions are 800/zoom and 1000/zoom. For best results
1.479 +therefore, choose zoom factors that do not require rounding when we calculate
1.480 +the number of appunits per device pixel; i.e. the zoom factor should divide 60,
1.481 +so 60/zoom is an integer.
1.482 +
1.483 +Setting Viewport Size: reftest-viewport-w/h="<int>"
1.484 +===================================================
1.485 +
1.486 +If either of the "reftest-viewport-w" and "reftest-viewport-h" attributes on
1.487 +the root element are non-zero, sets the CSS viewport to the given size in
1.488 +CSS pixels. This does not affect the size of the snapshot that is taken.
1.489 +
1.490 +Setting Async Scroll Mode: reftest-async-scroll attribute
1.491 +=========================================================
1.492 +
1.493 +If the "reftest-async-scroll" attribute is set on the root element, we try to
1.494 +enable async scrolling for the document. This is unsupported in many
1.495 +configurations.
1.496 +
1.497 +Setting Displayport Dimensions: reftest-displayport-x/y/w/h="<int>"
1.498 +===================================================================
1.499 +
1.500 +If any of the "reftest-displayport-x", "reftest-displayport-y",
1.501 +"reftest-displayport-w" and "reftest-displayport-h" attributes on the root
1.502 +element are nonzero, sets the displayport dimensions to the given bounds in
1.503 +CSS pixels. This does not affect the size of the snapshot that is taken.
1.504 +
1.505 +When the "reftest-async-scroll" attribute is set on the root element, *all*
1.506 +elements in the document are checked for "reftest-displayport-x/y/w/h" and have
1.507 +displayports set on them when those attributes are present.
1.508 +
1.509 +Testing Async Scrolling: reftest-async-scroll-x/y="<int>"
1.510 +=========================================================
1.511 +
1.512 +When the "reftest-async-scroll" attribute is set on the root element, for any
1.513 +element where either the "reftest-async-scroll-x" or "reftest-async-scroll-y
1.514 +attributes are nonzero, at the end of the test take the snapshot with the given
1.515 +offset (in CSS pixels) added to the async scroll offset.
1.516 +
1.517 +Printing Tests: class="reftest-print"
1.518 +=====================================
1.519 +
1.520 +Now that the patch for bug 374050 has landed
1.521 +(https://bugzilla.mozilla.org/show_bug.cgi?id=374050), it is possible to
1.522 +create reftests that run in a paginated context.
1.523 +
1.524 +The page size used is 5in wide and 3in tall (with the default half-inch
1.525 +margins). This is to allow tests to have less text and to make the
1.526 +entire test fit on the screen.
1.527 +
1.528 +There is a layout/reftests/printing directory for printing reftests; however,
1.529 +there is nothing special about this directory. You can put printing reftests
1.530 +anywhere that is appropriate.
1.531 +
1.532 +The suggested first lines for any printing test is
1.533 +<!DOCTYPE html><html class="reftest-print">
1.534 +<style>html{font-size:12pt}</style>
1.535 +
1.536 +The reftest-print class on the root element triggers the reftest to
1.537 +switch into page mode. Fixing the font size is suggested, although not
1.538 +required, because the pages are a fixed size in inches. The switch to page mode
1.539 +happens on load if the reftest-wait class is not present; otherwise it happens
1.540 +immediately after firing the MozReftestInvalidate event.
1.541 +
1.542 +The underlying layout support for this mode isn't really complete; it
1.543 +doesn't use exactly the same codepath as real print preview/print. In
1.544 +particular, scripting and frames are likely to cause problems; it is untested,
1.545 +though. That said, it should be sufficient for testing layout issues related
1.546 +to pagination.
1.547 +
1.548 +Plugin and IPC Process Crash Tests: class="reftest-expect-process-crash"
1.549 +========================================================================
1.550 +
1.551 +If you are running a test that causes an out-of-process plugin or IPC process
1.552 +under Electrolysis to crash as part of a reftest, this will cause process
1.553 +crash minidump files to be left in the profile directory. The test
1.554 +infrastructure that runs the reftests will notice these minidump files and
1.555 +dump out information from them, and these additional error messages in the logs
1.556 +can end up erroneously being associated with other errors from the reftest run.
1.557 +They are also confusing, since the appearance of "PROCESS-CRASH" messages in
1.558 +the test run output can seem like a real problem, when in fact it is the
1.559 +expected behavior.
1.560 +
1.561 +To indicate to the reftest framework that a test is expecting a plugin or
1.562 +IPC process crash, have the test include "reftest-expect-process-crash" as
1.563 +one of the root element's classes by the time the test has finished. This will
1.564 +cause any minidump files that are generated while running the test to be removed
1.565 +and they won't cause any error messages in the test run output.
1.566 +
1.567 +Skip Forcing A Content Process Layer-Tree Update: reftest-no-sync-layers attribute
1.568 +==================================================================================
1.569 +
1.570 +Normally when an multi-process reftest test ends, we force the content process
1.571 +to push a layer-tree update to the compositor before taking the snapshot.
1.572 +Setting the "reftest-no-sync-layers" attribute on the root element skips this
1.573 +step, enabling testing that layer-tree updates are being correctly generated.
1.574 +However the test must manually wait for a MozAfterPaint event before ending.
