Tweak the descriptions of the various types of layout tests.

docs/testing/writing_layout_tests.md

 # Writing Layout Tests
 
 _Layout tests_ is a bit of a misnomer. This term is
 [a part of our WebKit heritage](https://webkit.org/blog/1452/layout-tests-theory/),
 and we use it to refer to every test that is written as a Web page (HTML, SVG,
 or XHTML) and lives in
 [third_party/WebKit/LayoutTests/](../../third_party/WebKit/LayoutTests).
 
 [TOC]
 
@@ skipping 31 matching lines @@
 * *JavaScript Tests* are the layout test implementation of
   [xUnit tests](https://en.wikipedia.org/wiki/XUnit). These tests contain
   assertions written in JavaScript, and pass if the assertions evaluate to
   true.
 * *Reference Tests* render a test page and a reference page, and pass if the two
   renderings are identical, according to a pixel-by-pixel comparison. These
   tests are less robust, harder to debug, and significantly slower than
   JavaScript tests, and are only used when JavaScript tests are insufficient,
   such as when testing paint code.
 * *Pixel Tests* render a test page and compare the result against a pre-rendered
-  baseline image in the repository. Pixel tests are less robust than all
-  alternatives listed above, because the rendering of a page is influenced by
+  baseline image in the repository. Pixel tests are less robust than the
+  first two types, because the rendering of a page is influenced by
   many factors such as the host computer's graphics card and driver, the
   platform's text rendering system, and various user-configurable operating
   system settings. For this reason, it is common for a pixel test to have a
-  different reference image for each platform that Blink is tested on. Pixel
-  tests are least preferred, because the reference images are
-  [quite cumbersome to manage](./layout_test_expectations.md).
-* *Dump Render Tree (DRT) Tests* output a textual representation of the render
+  different reference image for each platform that Blink is tested on, and
+  the reference images are
+  [quite cumbersome to manage](./layout_test_expectations.md). You
+  should only write a pixel test if you cannot use a reference test. By default
+  a pixel test will also dump the render tree as text output, so they are
+  similar to ...
+* *Render tree tests*, which output a textual representation of the render

[cbiesinger, 2016/12/02 22:15:22]

We call it Layout Tree now, fwiw

   tree, which is the key data structure in Blink's page rendering system. The
-  test passes if the output matches a baseline text file in the repository. In
-  addition to their text result, DRT tests can also produce an image result
-  which is compared to an image baseline, similarly to pixel tests (described
-  above). A DRT test with two results (text and image) passes if _both_ results
-  match the baselines in the repository. DRT tests are less desirable than all
-  the alternatives, because they depend on a browser implementation detail.
-
+  test passes if the output matches a baseline text file in the repository.
+  Render tree tests are used as a last resort to test the internal quirks of
+  the implementation, and they should be avoided in favor of one of the earlier
+  options.
 ## General Principles
 
 The principles below are adapted from
 [Test the Web Forward's Test Format Guidelines](http://testthewebforward.org/docs/test-format-guidelines.html)
 and
 [WebKit's Wiki page on Writing good test cases](https://trac.webkit.org/wiki/Writing%20Layout%20Tests%20for%20DumpRenderTree).
 
 * Tests should be **concise**, without compromising on the principles below.
   Every element and piece of code on the page should be necessary and relevant
   to what is being tested. For example, don't build a fully functional signup
@@ skipping 609 matching lines @@
 
 ### Tests that need to paint, raster, or draw a frame of intermediate output
 
 A layout test does not actually draw frames of output until the test exits.
 Tests that need to generate a painted frame can use
 `window.testRunner.displayAsyncThen`, which will run the machinery to put up a
 frame, then call the passed callback. There is also a library at
 `fast/repaint/resources/text-based-repaint.js` to help with writing paint
 invalidation and repaint tests.
 
-## Dump Render Tree (DRT) Tests
+## Render tree Tests
 
-A Dump Render Tree test renders a web page and produces up to two results, which
+A render tree test renders a web page and produces up to two results, which
 are compared against baseline files:
 
 * All tests output a textual representation of Blink's
   [render tree](https://developers.google.com/web/fundamentals/performance/critical-rendering-path/render-tree-construction),
   which is compared against an `-expected.txt` text baseline.
 * Some tests also output the image of the rendered page, which is compared
   against an `-expected.png` image baseline, using the same method as pixel
   tests.
 
-TODO: Document the API used by DRT tests to opt out of producing image results.
+Whether you want a pixel test or a render tree test depends on whether
+you care about the visual image, the details of how that image was
+constructed, or both. It is possible for multiple render trees to produce
+the same pixel output, so it is important to make it clear in the test
+which outputs you really care about.
 
-A DRT test passes if _all_ of its results match their baselines. Like pixel
-tests, the output of DRT tests depends on platform-specific mechanisms, so DRT
-tests often require per-platform baselines. Furthermore, DRT tests depend on the
-render tree data structure, which means that if we replace the render tree data
-structure, we will need to look at each DRT test and consider whether it is
-still meaningful.
+TODO: Document the API used by render tree tests to opt out of producing image
+results.

[m_gsnedders, 2016/12/02 14:16:44]

Given the intro above says that by default "a pixel test will also dump the
render tree", there should equally be a TODO above as to how to opt out of
producing a render tree.

 
-For these reasons, DRT tests should **only** be used to cover aspects of the
-layout code that can only be tested by looking at the render tree. Any
-combination of the other test types is preferable to a DRT test. DRT tests are
+A render tree test passes if _all_ of its results match their baselines. Like pixel
+tests, the output of render tree tests depends on platform-specific details,
+so render tree tests often require per-platform baselines. Furthermore,
+since the tests obviously depend on the render tree structure,
+that means that if we change the render tree you have to rebaseline each 
+render tree test to see if the results are still correct and whether the test
+is still meaningful. There are actually many cases where the render tree

[pwnall, 2016/12/02 03:20:48]

Could "many cases" link to a crbug that tracks removing or updating these tests?

+output is misstated (i.e., wrong), because people didn't want to have to update
+existing baselines and tests. This is really unfortunate and confusing.
+
+For these reasons, render tree tests should **only** be used to cover aspects
+of the layout code that can only be tested by looking at the render tree. Any
+combination of the other test types is preferable to a render tree test. 
+render tree tests are

[m_gsnedders, 2016/12/02 14:16:44]

(grammar): needs a capital R

 [inherited from WebKit](https://webkit.org/blog/1456/layout-tests-practice/), so
-the repository may have some unfortunate examples of DRT tests.
+the repository may have some unfortunate examples of render tree tests.
 
-The following page is an example of a DRT test.
+
+The following page is an example of a render tree test.
 
 ```html
 <!doctype html>
 <meta charset="utf-8">
 <style>
 body { font: 10px Ahem; }
 span::after {
   content: "pass";
   color: green;
 }
@@ skipping 20 matching lines @@
           LayoutInline {<pseudo:after>} at (0,0) size 40x10 [color=#008000]
             LayoutTextFragment (anonymous) at (430,0) size 40x10
               text run at (430,0) width 40: "pass"
 ```
 
 Notice that the test result above depends on the size of the `<p>` text. The
 test page uses the Ahem font (introduced above), whose main design goal is
 consistent cross-platform rendering. Had the test used another font, its text
 baseline would have depended on the fonts installed on the testing computer, and
 on the platform's font rendering system. Please follow the pixel tests
-guidelines and write reliable DRT tests!
+guidelines and write reliable render tree tests!
 
 WebKit's render tree is described in
 [a series of posts](https://webkit.org/blog/114/webcore-rendering-i-the-basics/)
 on WebKit's blog. Some of the concepts there still apply to Blink's render tree.
 
 ## Directory Structure
 
 The [LayoutTests directory](../../third_party/WebKit/LayoutTests) currently
 lacks a strict, formal structure. The following directories have special
 meaning:
 
 * The `http/` directory hosts tests that require an HTTP server (see above).
 * The `resources/` subdirectory in every directory contains binary files, such
   as media files, and code that is shared by multiple test files.
 
 *** note
 Some layout tests consist of a minimal HTML page that references a JavaScript
 file in `resources/`. Please do not use this pattern for new tests, as it goes
 against the minimality principle. JavaScript and CSS files should only live in
 `resources/` if they are shared by at least two test files.
 ***