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

[pwnall, 2016/12/02 02:35:10]

Thanks for catching this inconsistency!

   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
   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. Most render tree tests also produce image results, and so these

[pwnall, 2016/12/02 02:35:10]

I think that the text starting at "Most render tree tests" belongs in a promo in
the section dedicated to them. The text before it seems sufficient for the
purpose of choosing between test types.

[Dirk Pranke, 2016/12/02 02:44:54]

Okay.

+  tests are easily confused with Pixel tests. The distinction lies in 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.
 
 ## 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
@@ skipping 610 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

[pwnall, 2016/12/02 02:35:10]

Can you please make the name here consistent with the new name above? There are
a bunch of DRTs sprinkled over this section.

[Dirk Pranke, 2016/12/02 02:44:54]

Will do. It didn't even occur to me to check for multiple references :).

 
 A Dump 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.
@@ skipping 69 matching lines @@
 * 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.
 ***