Bug 1932978 [wpt PR 49339] - Update READMEs for animation tests, a=testonly

Automatic update from web-platform-tests
Update READMEs for animation tests

First in a series of patches to document best practices for animation
tests. This patch adds a readme for non-WPT animation tests, and
updates the readme for CSS transitions.  Each tip was recently used to
fix a flake / failure introduced with the migration of css transition
tests from using run_web_test.py to run_wpt_test.py.

Change-Id: Iaba7ea397c4f55a090b08a71c046b96c64453bd9
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6037955
Reviewed-by: Olga Gerchikov <gerchikomicrosoft.com>
Commit-Queue: Kevin Ellis <keverschromium.org>
Cr-Commit-Position: refs/heads/main{#1387067}

--

wpt-commits: c27cc4faeeb1b4b5ce7f98e29a7f4aba5d6ac6ac
wpt-pr: 49339

UltraBlame original commit: 1d3bbbcde9e521bf0e9081d929ab9ba0e05c803b

Author: marco-c

testing/web-platform/tests/css/css-transitions/README.md

@@ -47,6 +47,102 @@ To make individual tests a bit more readable, a lot of the test-functionality ha
 2. disable final cleanup by commenting out `done` and `teardown` callbacks
 3. possibly increase the `duration` and disable the `#offscreen` (by simply naming it `#off-screen`)
 
+## Tips to avoid test flakes ##
+
+### Making style update deterministic ####
+
+Timing characteristics vary widely across testing environments, and we need to
+be careful about making assumptions about the state of the testing environment
+to avoid race conditions.
+
+Here is an example of a test with a race condition.
+
+```css
+# target {
+  color: green;
+  transition: color 300ms;
+  transition-delay: -150ms;
+}
+```
+
+```javascript
+  test(() => {
+    target.style.color = 'pink';
+    assert_equals(getComputedStyle(target).color, ...);
+  }, ...);
+```
+The value of color will differ depending on whether the color "change" was
+captured as part of the initial style update. We cannot assume style and
+layout are clean at the start of a test.
+
+One way to fix this with the benefit of testing that a transition started is
+as follows:
+
+```javascript
+  test(() => {
+    assert_equals(document.getAnimations().length, 0,
+                  'Initially no running animations');
+    target.style.color = 'pink';
+    assert_equals(document.getAnimations().length, 1,
+                  'Color change triggers a CSS transition');
+    assert_equals(getComputedStyle(target).color, ...);
+  }, ...);
+````
+
+### Reftests and paint holding ###
+
+To avoid the flash of white when a navigating between pages, browsers may
+elect to freeze the contents until ready to render the page. All animations,
+CSS transitions included, have a ready promise that is resolved when the
+user agent has completed any set up and is ready to rendering the animation.
+
+Rather than simply creating the transition and calling takeScreenshot, a safer
+approach is as follows:
+
+```javascript
+window.onload = async () => {
+   ... test setup including starting  any transitions ...
+
+   const promises = document.getAnimations().map(anim => anim.ready);
+   await Promise.all(promises);
+   requestAnimationFrame(takeScreenshot);
+};
+```
+
+### Reftests and avoiding animation drift ###
+
+The animation API is largely asynchronous and an extra animation frame can
+easily cause misalignment of a reftest with its reference image. One
+approach to address the issue is to use a long duration animation with a
+negative transition delay to set the position. If using this approach, we can
+further reduce the potential for animation drift by using a step easing function
+or freeze at the midpoint by using cubic-bezier(0, 1, 1, 0) combined with a
+negative transition delay with a magnitude equal to half the duration.  Unless
+critical for the test to be performed on running transitions, a safe alternative
+is to pause the transitions.
+
+```javascript
+document.getAnimations().forEach(anim => anim.pause());
+```
+
+## Tips to reduce test runtime ##
+
+When testing for transitionend, it is not necessary to let the animation run its
+course. It may be tempting just to use a short duration animation, but safer is
+to accelerate the animation via the web-animations API. This gives us precise
+control over the test conditions.
+
+```javascript
+function fastForward(anim, progress) {
+  anim.currentTime = anim.effect.getTiming().duration * progress;
+}
+```
+
+If simply wanting to jump to the end of the transition, then calling
+anim.finish() does the trick.  This fast forwarding trick is also really
+useful for sampling a transition curve (testing whether a transition is
+discrete or continuous for example).
+
 
 ## Unspecified Behavior ##