| OLD | NEW |
| 1 # Layout Tests with Manual Fallback | 1 # Layout Tests with Manual Fallback |
| 2 | 2 |
| 3 Some Blink features cannot be automatically tested using the Web Platform. Prime | 3 Some Blink features cannot be automatically tested using the Web Platform. Prime |
| 4 examples are the APIs that require | 4 examples are the APIs that require |
| 5 [user activation](https://html.spec.whatwg.org/multipage/interaction.html#trigge
red-by-user-activation) | 5 [user activation](https://html.spec.whatwg.org/multipage/interaction.html#trigge
red-by-user-activation) |
| 6 (also known as _a user gesture_), such as [Full Screen](https://developer.mozill
a.org/en-US/docs/Web/API/Fullscreen_API). | 6 (also known as _a user gesture_), such as [Full Screen](https://developer.mozill
a.org/en-US/docs/Web/API/Fullscreen_API). |
| 7 Automated tests for these Blink features must rely on special APIs, which are | 7 Automated tests for these Blink features must rely on special APIs, which are |
| 8 only exposed in testing environments, and are therefore not available in a | 8 only exposed in testing environments, and are therefore not available in a |
| 9 normal browser session. | 9 normal browser session. |
| 10 | 10 |
| 11 A popular pattern used in these tests is to rely on the user to perform some | 11 A popular pattern used in these tests is to rely on the user to perform some |
| 12 manual steps in order to run the test case in a normal browser session. These | 12 manual steps in order to run the test case in a normal browser session. These |
| 13 tests are effectively | 13 tests are effectively |
| 14 [manual tests](http://testthewebforward.org/docs/manual-test.html), with | 14 [manual tests](http://web-platform-tests.org/writing-tests/manual.html), with |
| 15 additional JavaScript code that automatically performs the desired manual steps, | 15 additional JavaScript code that automatically performs the desired manual steps, |
| 16 when loaded in an environment that exposes the needed testing APIs. | 16 when loaded in an environment that exposes the needed testing APIs. |
| 17 | 17 |
| 18 ## Motivation | 18 ## Motivation |
| 19 | 19 |
| 20 Layout tests that degrade to manual tests in the absence of testing APIs have | 20 Layout tests that degrade to manual tests in the absence of testing APIs have |
| 21 the following benefits. | 21 the following benefits. |
| 22 | 22 |
| 23 * The manual test component can be debugged in a normal browser session, using | 23 * The manual test component can be debugged in a normal browser session, using |
| 24 the rich [developer tools](https://developer.chrome.com/devtools). Tests | 24 the rich [developer tools](https://developer.chrome.com/devtools). Tests |
| 25 without a manual fallback can only be debugged in the test runner. | 25 without a manual fallback can only be debugged in the test runner. |
| 26 * The manual tests can run in other browsers, making it easy to check whether | 26 * The manual tests can run in other browsers, making it easy to check whether |
| 27 our behavior matches other browsers. | 27 our behavior matches other browsers. |
| 28 * The layout tests can form the basis for manual tests that are contributed to | 28 * The layout tests can form the basis for manual tests that are contributed to |
| 29 the [Web Platform Tests Project](https://github.com/w3c/web-platform-tests). | 29 [web-platform-tests](./web_platform_tests.md). |
| 30 | 30 |
| 31 Therefore, the desirability of adding a manual fallback to a test heavily | 31 Therefore, the desirability of adding a manual fallback to a test heavily |
| 32 depends on whether the feature under test is a Web Platform feature or a | 32 depends on whether the feature under test is a Web Platform feature or a |
| 33 Blink-only feature, and on the developer's working style. The benefits above | 33 Blink-only feature, and on the developer's working style. The benefits above |
| 34 should be weighed against the added design effort needed to build a manual test, | 34 should be weighed against the added design effort needed to build a manual test, |
| 35 and the size and complexity introduced by the manual fallback. | 35 and the size and complexity introduced by the manual fallback. |
| 36 | 36 |
| 37 ## Development Tips | 37 ## Development Tips |
| 38 | 38 |
| 39 A natural workflow for writing a layout test that gracefully degrades to a | 39 A natural workflow for writing a layout test that gracefully degrades to a |
| (...skipping 70 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
| 110 fail when the APIs are not present. | 110 fail when the APIs are not present. |
| 111 * It uses [Promises](https://developer.mozilla.org/docs/Web/JavaScript/Reference
/Global_Objects/Promise) | 111 * It uses [Promises](https://developer.mozilla.org/docs/Web/JavaScript/Reference
/Global_Objects/Promise) |
| 112 to separate the test setup from the assertions. This is particularly helpful | 112 to separate the test setup from the assertions. This is particularly helpful |
| 113 for manual tests that depend on a sequence of events to occur, as Promises | 113 for manual tests that depend on a sequence of events to occur, as Promises |
| 114 offer a composable way to express waiting for asynchronous events that avoids | 114 offer a composable way to express waiting for asynchronous events that avoids |
| 115 [callback hell](http://stackabuse.com/avoiding-callback-hell-in-node-js/). | 115 [callback hell](http://stackabuse.com/avoiding-callback-hell-in-node-js/). |
| 116 | 116 |
| 117 Notice that the test is pretty heavy compared to a minimal JavaScript test that | 117 Notice that the test is pretty heavy compared to a minimal JavaScript test that |
| 118 does not rely on testing APIs. Only use testing APIs when the desired testing | 118 does not rely on testing APIs. Only use testing APIs when the desired testing |
| 119 conditions cannot be set up using Web Platform APIs. | 119 conditions cannot be set up using Web Platform APIs. |
| OLD | NEW |