| OLD | NEW |
| 1 # Layout Tests Tips | 1 # Layout Tests Tips |
| 2 | 2 |
| 3 The recommendations here are intended to help you write new tests that go | 3 The recommendations here are intended to help you write new tests that go |
| 4 through code review with a minimal number of round trips, remain useful as Blink | 4 through code review with a minimal number of round trips, remain useful as Blink |
| 5 evolves, and serve as an asset (rather than a liability) for the team. | 5 evolves, and serve as an asset (rather than a liability) for the team. |
| 6 | 6 |
| 7 While reading existing layout tests, please keep in mind that they represent | 7 While reading existing layout tests, please keep in mind that they represent |
| 8 snapshots taken over many years of an ever-evolving collective opinion of what | 8 snapshots taken over many years of an ever-evolving collective opinion of what |
| 9 good Web pages and solid tests should look like. Thus, it should not come as a | 9 good Web pages and solid tests should look like. Thus, it should not come as a |
| 10 surprise that most existing layout tests are not consistent with these | 10 surprise that most existing layout tests are not consistent with these |
| 11 recommendations, and are not even consistent with each other. | 11 recommendations, and are not even consistent with each other. |
| 12 | 12 |
| 13 *** note | 13 *** note |
| 14 This document intentionally uses _should_ a lot more than _must_, as defined in | 14 This document intentionally uses _should_ a lot more than _must_, as defined in |
| 15 [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). Writing layout tests is a | 15 [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt). Writing layout tests is a |
| 16 careful act of balancing many concerns, and this humble document cannot possibly | 16 careful act of balancing many concerns, and this humble document cannot possibly |
| 17 capture the context that rests in the head of an experienced Blink engineer. | 17 capture the context that rests in the head of an experienced Blink engineer. |
| 18 *** | 18 *** |
| 19 | 19 |
| 20 ## General Principles | 20 ## General Principles |
| 21 | 21 |
| 22 This section contains guidelines adopted from | 22 This section contains guidelines adopted from |
| 23 [Test the Web Forward's Test Format Guidelines](http://testthewebforward.org/doc
s/test-format-guidelines.html) | 23 [web-platform-tests documentation](http://web-platform-tests.org/writing-tests/g
eneral-guidelines.html) |
| 24 and | 24 and |
| 25 [WebKit's Wiki page on Writing good test cases](https://trac.webkit.org/wiki/Wri
ting%20Layout%20Tests%20for%20DumpRenderTree), | 25 [WebKit's Wiki page on Writing good test cases](https://trac.webkit.org/wiki/Wri
ting%20Layout%20Tests%20for%20DumpRenderTree), |
| 26 with Blink-specific flavoring. | 26 with Blink-specific flavoring. |
| 27 | 27 |
| 28 ### Concise | 28 ### Concise |
| 29 | 29 |
| 30 Tests should be **concise**, without compromising on the principles below. Every | 30 Tests should be **concise**, without compromising on the principles below. Every |
| 31 element and piece of code on the page should be necessary and relevant to what | 31 element and piece of code on the page should be necessary and relevant to what |
| 32 is being tested. For example, don't build a fully functional signup form if you | 32 is being tested. For example, don't build a fully functional signup form if you |
| 33 only need a text field or a button. | 33 only need a text field or a button. |
| (...skipping 52 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 86 | 86 |
| 87 ### Self-Describing | 87 ### Self-Describing |
| 88 | 88 |
| 89 Tests should be **self-describing**, so that a project member can recognize | 89 Tests should be **self-describing**, so that a project member can recognize |
| 90 whether a test passes or fails without having to read the specification of the | 90 whether a test passes or fails without having to read the specification of the |
| 91 feature being tested. | 91 feature being tested. |
| 92 | 92 |
| 93 `testharness.js` makes a test self-describing when used correctly. Other types | 93 `testharness.js` makes a test self-describing when used correctly. Other types |
| 94 of tests, such as reference tests and | 94 of tests, such as reference tests and |
| 95 [tests with manual fallback](./layout_tests_with_manual_fallback.md), | 95 [tests with manual fallback](./layout_tests_with_manual_fallback.md), |
| 96 [must be carefully designed](http://testthewebforward.org/docs/test-style-guidel
ines.html) | 96 [must be carefully designed](http://web-platform-tests.org/writing-tests/manual.
html#requirements-for-a-manual-test) |
| 97 to be self-describing. | 97 to be self-describing. |
| 98 | 98 |
| 99 ### Minimal | 99 ### Minimal |
| 100 | 100 |
| 101 Tests should require a **minimal** amount of cognitive effort to read and | 101 Tests should require a **minimal** amount of cognitive effort to read and |
| 102 maintain. | 102 maintain. |
| 103 | 103 |
| 104 Avoid depending on edge case behavior of features that aren't explicitly covered | 104 Avoid depending on edge case behavior of features that aren't explicitly covered |
| 105 by the test. For example, except where testing parsing, tests should contain | 105 by the test. For example, except where testing parsing, tests should contain |
| 106 valid markup (no parsing errors). | 106 valid markup (no parsing errors). |
| (...skipping 185 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 292 | 292 |
| 293 Tests that rely on the testing APIs exposed by WPT or Blink will not work when | 293 Tests that rely on the testing APIs exposed by WPT or Blink will not work when |
| 294 loaded in a standard browser environment. When writing such tests, default to | 294 loaded in a standard browser environment. When writing such tests, default to |
| 295 having the tests gracefully degrade to manual tests in the absence of the | 295 having the tests gracefully degrade to manual tests in the absence of the |
| 296 testing APIs. | 296 testing APIs. |
| 297 | 297 |
| 298 The | 298 The |
| 299 [document on layout tests with manual feedback](./layout_tests_with_manual_fallb
ack.md) | 299 [document on layout tests with manual feedback](./layout_tests_with_manual_fallb
ack.md) |
| 300 describes the approach in detail and highlights the trade-off between added test | 300 describes the approach in detail and highlights the trade-off between added test |
| 301 weight and ease of debugging. | 301 weight and ease of debugging. |
| OLD | NEW |