OLD | NEW |
1 # Writing Layout Tests | 1 # Writing Layout Tests |
2 | 2 |
3 _Layout tests_ is a bit of a misnomer. This term is | 3 _Layout tests_ is a bit of a misnomer. This term is |
4 [a part of our WebKit heritage](https://webkit.org/blog/1452/layout-tests-theory
/), | 4 [a part of our WebKit heritage](https://webkit.org/blog/1452/layout-tests-theory
/), |
5 and we use it to refer to every test that is written as a Web page (HTML, SVG, | 5 and we use it to refer to every test that is written as a Web page (HTML, SVG, |
6 or XHTML) and lives in | 6 or XHTML) and lives in |
7 [third_party/WebKit/LayoutTests/](../../third_party/WebKit/LayoutTests). | 7 [third_party/WebKit/LayoutTests/](../../third_party/WebKit/LayoutTests). |
8 | 8 |
9 [TOC] | 9 [TOC] |
10 | 10 |
(...skipping 320 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
331 specification URL (in `<link rel="help">`) is almost always relevant, and is | 331 specification URL (in `<link rel="help">`) is almost always relevant, and is |
332 incredibly helpful to a developer who needs to understand the test quickly. | 332 incredibly helpful to a developer who needs to understand the test quickly. |
333 | 333 |
334 Below is a skeleton for a JavaScript test embedded in an HTML page. Note that, | 334 Below is a skeleton for a JavaScript test embedded in an HTML page. Note that, |
335 in order to follow the minimality guideline, the test omits the tags `<html>`, | 335 in order to follow the minimality guideline, the test omits the tags `<html>`, |
336 `<head>`, and `<body>`, as they can be inferred by the HTML parser. | 336 `<head>`, and `<body>`, as they can be inferred by the HTML parser. |
337 | 337 |
338 ```html | 338 ```html |
339 <!doctype html> | 339 <!doctype html> |
340 <meta charset="utf-8"> | 340 <meta charset="utf-8"> |
| 341 <title>JavaScript: the true literal</title> |
341 <link rel="help" href="https://tc39.github.io/ecma262/#sec-boolean-literals"> | 342 <link rel="help" href="https://tc39.github.io/ecma262/#sec-boolean-literals"> |
342 <meta name="assert" value="The true literal is equal to itself and immutable"> | 343 <meta name="assert" value="The true literal is equal to itself and immutable"> |
343 <script src="/resources/testharness.js"></script> | 344 <script src="/resources/testharness.js"></script> |
344 <script src="/resources/testharnessreport.js"></script> | 345 <script src="/resources/testharnessreport.js"></script> |
345 <script> | 346 <script> |
346 'use strict'; | 347 'use strict'; |
347 | 348 |
348 // Synchronous test example. | 349 // Synchronous test example. |
349 test(() => { | 350 test(() => { |
350 const value = true; | 351 const value = true; |
(...skipping 16 matching lines...) Expand all Loading... |
367 }).then(value => { | 368 }).then(value => { |
368 assert_true(value); | 369 assert_true(value); |
369 }); | 370 }); |
370 }, 'The literal true used to resolve a Promise'); | 371 }, 'The literal true used to resolve a Promise'); |
371 | 372 |
372 </script> | 373 </script> |
373 ``` | 374 ``` |
374 | 375 |
375 Some points that are not immediately obvious from the example: | 376 Some points that are not immediately obvious from the example: |
376 | 377 |
377 * The `<meta name="assert">` describes the purpose of the entire file. | 378 * The `<meta name="assert">` describes the purpose of the entire file, and |
| 379 is not redundant to `<title>`. Don't add a `<meta name="assert">` when the |
| 380 information in the `<title>` is sufficient. |
378 * When calling an `assert_` function that compares two values, the first | 381 * When calling an `assert_` function that compares two values, the first |
379 argument is the actual value (produced by the functionality being tested), and | 382 argument is the actual value (produced by the functionality being tested), and |
380 the second argument is the expected value (known good, golden). The order | 383 the second argument is the expected value (known good, golden). The order |
381 is important, because the testing harness relies on it to generate expressive | 384 is important, because the testing harness relies on it to generate expressive |
382 error messages that are relied upon when debugging test failures. | 385 error messages that are relied upon when debugging test failures. |
383 * The assertion description (the string argument to `assert_` methods) conveys | 386 * The assertion description (the string argument to `assert_` methods) conveys |
384 the way the actual value was obtained. | 387 the way the actual value was obtained. |
385 * If the expected value doesn't make it clear, the assertion description | 388 * If the expected value doesn't make it clear, the assertion description |
386 should explain the desired behavior. | 389 should explain the desired behavior. |
387 * Test cases with a single assertion should omit the assertion's description | 390 * Test cases with a single assertion should omit the assertion's description |
388 when it is sufficiently clear. | 391 when it is sufficiently clear. |
389 * Each test case describes the circumstance that it tests, without being | 392 * Each test case describes the circumstance that it tests, without being |
390 redundant. | 393 redundant. |
391 * Do not start test case descriptions with redundant terms like "Testing" | 394 * Do not start test case descriptions with redundant terms like "Testing" |
392 or "Test for". | 395 or "Test for". |
| 396 * Test files with a single test case should omit the test case description. |
| 397 The file's `<title>` should be sufficient to describe the scenario being |
| 398 tested. |
393 * Asynchronous tests have a few subtleties. | 399 * Asynchronous tests have a few subtleties. |
394 * The `async_test` wrapper calls its function with a test case argument that | 400 * The `async_test` wrapper calls its function with a test case argument that |
395 is used to signal when the test case is done, and to connect assertion | 401 is used to signal when the test case is done, and to connect assertion |
396 failures to the correct test. | 402 failures to the correct test. |
397 * `t.done()` must be called after all the test case's assertions have | 403 * `t.done()` must be called after all the test case's assertions have |
398 executed. | 404 executed. |
399 * Test case assertions (actually, any callback code that can throw | 405 * Test case assertions (actually, any callback code that can throw |
400 exceptions) must be wrapped in `t.step_func()` calls, so that | 406 exceptions) must be wrapped in `t.step_func()` calls, so that |
401 assertion failures and exceptions can be traced back to the correct test | 407 assertion failures and exceptions can be traced back to the correct test |
402 case. | 408 case. |
(...skipping 100 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
503 manual steps to a minimum, and having simple and clear instructions that | 509 manual steps to a minimum, and having simple and clear instructions that |
504 describe all the configuration changes and user gestures that match the effect | 510 describe all the configuration changes and user gestures that match the effect |
505 of the Blink-specific APIs used by the test. | 511 of the Blink-specific APIs used by the test. |
506 | 512 |
507 Below is an example of a fairly minimal test that uses a Blink-Specific API | 513 Below is an example of a fairly minimal test that uses a Blink-Specific API |
508 (`window.eventSender`), and gracefully degrades to a manual test. | 514 (`window.eventSender`), and gracefully degrades to a manual test. |
509 | 515 |
510 ```html | 516 ```html |
511 <!doctype html> | 517 <!doctype html> |
512 <meta charset="utf-8"> | 518 <meta charset="utf-8"> |
| 519 <title>DOM: Event.isTrusted for UI events</title> |
513 <link rel="help" href="https://dom.spec.whatwg.org/#dom-event-istrusted"> | 520 <link rel="help" href="https://dom.spec.whatwg.org/#dom-event-istrusted"> |
514 <link rel="help" href="https://dom.spec.whatwg.org/#constructing-events"> | 521 <link rel="help" href="https://dom.spec.whatwg.org/#constructing-events"> |
515 <meta name="assert" | 522 <meta name="assert" |
516 content="Event.isTrusted is true for events generated by user interaction"> | 523 content="Event.isTrusted is true for events generated by user interaction"> |
517 <script src="../../resources/testharness.js"></script> | 524 <script src="../../resources/testharness.js"></script> |
518 <script src="../../resources/testharnessreport.js"></script> | 525 <script src="../../resources/testharnessreport.js"></script> |
519 | 526 |
520 <p>Please click on the button below.</p> | 527 <p>Please click on the button below.</p> |
521 <button>Click Me!</button> | 528 <button>Click Me!</button> |
522 | 529 |
(...skipping 351 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
874 * The `http/` directory hosts tests that require an HTTP server (see above). | 881 * The `http/` directory hosts tests that require an HTTP server (see above). |
875 * The `resources/` subdirectory in every directory contains binary files, such | 882 * The `resources/` subdirectory in every directory contains binary files, such |
876 as media files, and code that is shared by multiple test files. | 883 as media files, and code that is shared by multiple test files. |
877 | 884 |
878 *** note | 885 *** note |
879 Some layout tests consist of a minimal HTML page that references a JavaScript | 886 Some layout tests consist of a minimal HTML page that references a JavaScript |
880 file in `resources/`. Please do not use this pattern for new tests, as it goes | 887 file in `resources/`. Please do not use this pattern for new tests, as it goes |
881 against the minimality principle. JavaScript and CSS files should only live in | 888 against the minimality principle. JavaScript and CSS files should only live in |
882 `resources/` if they are shared by at least two test files. | 889 `resources/` if they are shared by at least two test files. |
883 *** | 890 *** |
OLD | NEW |