undefined reference to 'JSC::B3::BasicBlock::fallThrough() const
[WebKit-https.git] / LayoutTests / http / wpt / web-animations / README.md
1 Web Animations Test Suite
2 =========================
3
4 Specification: https://w3c.github.io/web-animations/
5
6
7 Guidelines for writing tests
8 ----------------------------
9
10 *   Try to follow the spec outline where possible.
11
12     For example, if you want to test setting the start time, you might be
13     tempted to put all the tests in:
14
15     > `/web-animations/interfaces/Animation/startTime.html`
16
17     However, in the spec most of the logic is in the “Set the animation
18     start time“ procedure in the “Timing model” section.
19
20     Instead, try something like:
21
22     > *   `/web-animations/timing-model/animations/set-the-animation-start-time.html`<br>
23     >     Tests all the branches and inputs to the procedure as defined in the
24     >     spec (using the `Animation.startTime` API).
25     > *   `/web-animations/interfaces/Animation/startTime.html`<br>
26     >     Tests API-layer specific issues like mapping unresolved values to
27     >      null, etc.
28
29     On that note, two levels of subdirectories is enough even if the spec has
30     deeper nesting.
31
32     Note that most of the existing tests in the suite _don't_ do this well yet.
33     That's the direction we're heading, however.
34
35 *   Test the spec.
36
37     *   If the spec defines a timing calculation that is directly
38         reflected in the iteration progress
39         (i.e. `anim.effect.getComputedTiming().progress`), test that instead
40         of calling `getComputedStyle(elem).marginLeft`.
41
42     *   Likewise, don't add needless tests for `anim.playbackState`.
43         The playback state is a calculated value based on other values.
44         It's rarely necessary to test directly unless you need, for example,
45         to check that a pending task is scheduled (which isn't observable
46         elsewhere other than waiting for the corresponding promise to
47         complete).
48
49 *   Try to keep tests as simple and focused as possible.
50
51     e.g.
52
53       ```javascript
54       test(function(t) {
55         const animation = createDiv(t).animate(null);
56         assert_class_string(animation, 'Animation', 'Returned object is an Animation');
57       }, 'Element.animate() creates an Animation object');
58       ```
59
60       ```javascript
61       test(function(t) {
62         assert_throws({ name: 'TypeError' }, function() {
63           createDiv(t).animate(null, -1);
64         });
65       }, 'Setting a negative duration throws a TypeError');
66       ```
67
68       ```javascript
69       promise_test(function(t) {
70         const animation = createDiv(t).animate(null, 100 * MS_PER_SEC);
71         return animation.ready.then(function() {
72           assert_greater_than(animation.startTime, 0, 'startTime when running');
73         });
74       }, 'startTime is resolved when running');
75       ```
76
77     If you're generating complex test loops and factoring out utility functions
78     that affect the logic of the test (other than, say, simple assertion utility
79     functions), you're probably doing it wrong.
80
81     It should be possible to understand exactly what the test is doing at a
82     glance without having to scroll up and down the test file and refer to
83     other files.
84
85     See Justin Searls' presentation, [&ldquo;How to stop hating your
86     tests&rdquo;](http://blog.testdouble.com/posts/2015-11-16-how-to-stop-hating-your-tests.html)
87     for some tips on making your tests simpler.
88
89 *   Assume tests will run on under-performing hardware where the time between
90     animation frames might run into 10s of seconds.
91     As a result, animations that are expected to still be running during
92     the test should be at least 100s in length.
93
94 *   Avoid using `GLOBAL_CONSTS` that make the test harder to read.
95     It's fine to repeat the the same parameter values like `100 * MS_PER_SEC`
96     over and over again since it makes it easy to read and debug a test in
97     isolation.
98     Remember, even if we do need to make all tests take, say 200s each, text
99     editors are very good at search and replace.
100
101 *   Use the `assert_times_equal` assertion for comparing calculated times.
102     It tests times are equal using the precision recommended in the spec whilst
103     allowing implementations to override the function to meet their own
104     precision requirements.
105
106 *   There are quite a few bad tests in the repository. We're learning as
107     we go. Don't just copy them blindly&mdash;please fix them!