New documentation on writing LayoutTests.

docs/testing/layout_tests.md

 # Layout Tests
 
 Layout tests are used by Blink to test many components, including but not
 limited to layout and rendering. In general, layout tests involve loading pages
 in a test renderer (`content_shell`) and comparing the rendered output or
 JavaScript output against an expected output file.
 
+This document covers running and debugging existing layout tests. See the
+[Writing Layout Tests documentation](./layout_test_writing.md) if you find
+yourself writing layout tests.
+
 [TOC]
 
 ## Running Layout Tests
 
 ### Initial Setup
 
 Before you can run the layout tests, you need to build the `blink_tests` target
 to get `content_shell` and all of the other needed binaries.
 
 ```bash
@@ skipping 37 matching lines @@
 For Android (if your build directory is `out/android`):
 
 ```bash
 python third_party/WebKit/Tools/Scripts/run-webkit-tests -t android --android
 ```
 
 Tests marked as `[ Skip ]` in
 [TestExpectations](../../third_party/WebKit/LayoutTests/TestExpectations)
 won't be run at all, generally because they cause some intractable tool error.
 To force one of them to be run, either rename that file or specify the skipped
-test as the only one on the command line (see below).
+test as the only one on the command line (see below). Read the
+[Layout Test Expectations documentation](./layout_test_expectations.md) to learn
+more about TestExpectations and related files.
 
-Note that currently only the tests listed in
+*** promo
+Currently only the tests listed in
 [SmokeTests](../../third_party/WebKit/LayoutTests/SmokeTests)
 are run on the Android bots, since running all layout tests takes too long on
 Android (and may still have some infrastructure issues). Most developers focus
 their Blink testing on Linux. We rely on the fact that the Linux and Android
 behavior is nearly identical for scenarios outside those covered by the smoke
 tests.
+***
 
 To run only some of the tests, specify their directories or filenames as
 arguments to `run_webkit_tests.py` relative to the layout test directory
 (`src/third_party/WebKit/LayoutTests`). For example, to run the fast form tests,
 use:
 
 ```bash
 Tools/Scripts/run-webkit-tests fast/forms
 ```
 
@@ skipping 88 matching lines @@
 causes the test shell to crash is marked as "crashed", and one that takes longer
 than a certain amount of time to complete is aborted and marked as "timed out".
 A row of dots in the script's output indicates one or more tests that passed.
 
 ## Test expectations
 
 The
 [TestExpectations](../../WebKit/LayoutTests/TestExpectations) file (and related
 files, including
 [skia_test_expectations.txt](../../skia/skia_test_expectations.txt))
-contains the list of all known layout test failures. See
-[Test Expectations](./layout_test_expectations.md)
-for more on this.
+contains the list of all known layout test failures. See the
+[Layout Test Expectations documentation](./layout_test_expectations.md) for more
+on this.
 
 ## Testing Runtime Flags
 
 There are two ways to run layout tests with additional command-line arguments:
 
 * Using `--additional-driver-flag`:
 
   ```bash
   run-webkit-tests --additional-driver-flag=--blocking-repaint
   ```
@@ skipping 73 matching lines @@
 
 * Components: a sub-component of Blink
 * OS: **All** (or whichever OS the failure is on)
 * Priority: 2 (1 if it's a crash)
 * Type: **Bug**
 * Labels: **Test-Layout**
 
 You can also use the _Layout Test Failure_ template, which will pre-set these
 labels for you.
 
-## Writing Layout Tests
-
-###  Pixel Tests
-
-TODO: Write documentation here.
-
-### Reference Tests
-
-TODO: Write documentation here.
-
-### Script Tests
-
-These tests use a JavaScript test harness and test cases written in script to
-exercise features and make assertions about the behavior. Generally, new tests
-are written using the [testharness.js](https://github.com/w3c/testharness.js/)
-test harness, which is also heavily used in the cross-vendor
-[web-platform-tests](https://github.com/w3c/web-platform-tests) project. Tests
-written with testharness.js generally look something like the following:
-
-```html
-<!DOCTYPE html>
-<script src="/resources/testharness.js"></script>
-<script src="/resources/testharnessreport.js"></script>
-<script>
-test(t => {
-  var x = true;
-  assert_true(x);
-}, "Truth is true.");
-</script>
-```
-
-Many older tests are written using the **js-test**
-(`LayoutTests/resources/js-test.js`) test harness. This harness is
-**deprecated**, and should not be used for new tests. The tests call
-`testRunner.dumpAsText()` to signal that the page content should be dumped and
-compared against an \*-expected.txt file, and optionally
-`testRunner.waitUntilDone()` and `testRunner.notifyDone()` for asynchronous
-tests.
-
-### Tests that use a HTTP Server
-
-By default, tests are loaded as if via `file:` URLs. Some web platform features
-require tests served via HTTP or HTTPS, for example relative paths (`src=/foo`)
-or features restricted to secure protocols.
-
-HTTP tests are those tests that are under `LayoutTests/http/tests` (or virtual
-variants). Use a locally running HTTP server (Apache) to run. Tests are served
-off of ports 8000, 8080 for HTTP and 8443 for HTTPS. If you run the tests using
-`run-webkit-tests`, the server will be started automatically.To run the server
-manually to reproduce or debug a failure:
-
-```bash
-cd src/third_party/WebKit/Tools/Scripts
-run-blink-httpd start
-```
-
-The layout tests will be served from `http://127.0.0.1:8000`. For example, to
-run the test `http/tests/serviceworker/chromium/service-worker-allowed.html`,
-navigate to
-`http://127.0.0.1:8000/serviceworker/chromium/service-worker-allowed.html`. Some
-tests will behave differently if you go to 127.0.0.1 instead of localhost, so
-use 127.0.0.1.
-
-To kill the server, run `run-blink-httpd --server stop`, or just use `taskkill`
-or the Task Manager on Windows, and `killall` or Activity Monitor on MacOS.
-
-The test server sets up an alias to `LayoutTests/resources` directory. In HTTP
-tests, you can access the testing framework at e.g.
-`src="/js-test-resources/js-test.js"`.
-
-### Writing 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. If
-it is required to generate a painted frame, then 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.
-
-#### Layout test support for `testRunner`
-
-Some layout tests rely on the testRunner object to expose configuration for
-mocking the platform. This is provided in content_shell, here's a UML diagram of
-testRunner bindings configuring platform implementation:
-
-[![UML of testRunner bindings configuring platform implementation](https://docs.google.com/drawings/u/1/d/1KNRNjlxK0Q3Tp8rKxuuM5mpWf4OJQZmvm9_kpwu_Wwg/export/svg?id=1KNRNjlxK0Q3Tp8rKxuuM5mpWf4OJQZmvm9_kpwu_Wwg&pageid=p)](https://docs.google.com/drawings/d/1KNRNjlxK0Q3Tp8rKxuuM5mpWf4OJQZmvm9_kpwu_Wwg/edit)
-
-[Writing reliable layout tests](https://docs.google.com/document/d/1Yl4SnTLBWmY1O99_BTtQvuoffP8YM9HZx2YPkEsaduQ/edit)
-
 ## Debugging Layout Tests
 
 After the layout tests run, you should get a summary of tests that pass or fail.
 If something fails unexpectedly (a new regression), you will get a content_shell
 window with a summary of the unexpected failures. Or you might have a failing
 test in mind to investigate. In any case, here are some steps and tips for
 finding the problem.
 
 * Take a look at the result. Sometimes tests just need to be rebaselined (see
   below) to account for changes introduced in your patch.
@@ skipping 179 matching lines @@
 See
 [bugs with the component Blink>Infra](https://bugs.chromium.org/p/chromium/issues/list?can=2&q=component%3ABlink%3EInfra)
 for issues related to Blink tools, include the layout test runner.
 
 * Windows and Linux: Do not copy and paste while the layout tests are running,
   as it may interfere with the editing/pasteboard and other clipboard-related
   tests. (Mac tests swizzle NSClipboard to avoid any conflicts).
 * If QuickTime is not installed, the plugin tests
   `fast/dom/object-embed-plugin-scripting.html` and
   `plugins/embed-attributes-setting.html` are expected to fail.