dom/animation/test/testcommon.js

   1 /* Any copyright is dedicated to the Public Domain.
   2  * http://creativecommons.org/publicdomain/zero/1.0/ */
   3
   4 /**
   5  * Use this variable if you specify duration or some other properties
   6  * for script animation.
   7  * E.g., div.animate({ opacity: [0, 1] }, 100 * MS_PER_SEC);
   8  *
   9  * NOTE: Creating animations with short duration may cause intermittent
  10  * failures in asynchronous test. For example, the short duration animation
  11  * might be finished when animation.ready has been fulfilled because of slow
  12  * platforms or busyness of the main thread.
  13  * Setting short duration to cancel its animation does not matter but
  14  * if you don't want to cancel the animation, consider using longer duration.
  15  */
  16 const MS_PER_SEC = 1000;
  17
  18 /* The recommended minimum precision to use for time values[1].
  19  *
  20  * [1] https://drafts.csswg.org/web-animations/#precision-of-time-values
  21  */
  22 var TIME_PRECISION = 0.0005; // ms
  23
  24 /*
  25  * Allow implementations to substitute an alternative method for comparing
  26  * times based on their precision requirements.
  27  */
  28 function assert_times_equal(actual, expected, description) {
  29   assert_approx_equals(actual, expected, TIME_PRECISION * 2, description);
  30 }
  31
  32 /*
  33  * Compare a time value based on its precision requirements with a fixed value.
  34  */
  35 function assert_time_equals_literal(actual, expected, description) {
  36   assert_approx_equals(actual, expected, TIME_PRECISION, description);
  37 }
  38
  39 /*
  40  * Compare matrix string like 'matrix(1, 0, 0, 1, 100, 0)'.
  41  * This function allows error, 0.01, because on Android when we are scaling down
  42  * the document, it results in some errors.
  43  */
  44 function assert_matrix_equals(actual, expected, description) {
  45   var matrixRegExp = /^matrix\((.+),(.+),(.+),(.+),(.+),(.+)\)/;
  46   assert_regexp_match(actual, matrixRegExp, "Actual value should be a matrix");
  47   assert_regexp_match(
  48     expected,
  49     matrixRegExp,
  50     "Expected value should be a matrix"
  51   );
  52
  53   var actualMatrixArray = actual.match(matrixRegExp).slice(1).map(Number);
  54   var expectedMatrixArray = expected.match(matrixRegExp).slice(1).map(Number);
  55
  56   assert_equals(
  57     actualMatrixArray.length,
  58     expectedMatrixArray.length,
  59     "Array lengths should be equal (got '" +
  60       expected +
  61       "' and '" +
  62       actual +
  63       "'): " +
  64       description
  65   );
  66   for (var i = 0; i < actualMatrixArray.length; i++) {
  67     assert_approx_equals(
  68       actualMatrixArray[i],
  69       expectedMatrixArray[i],
  70       0.01,
  71       "Matrix array should be equal (got '" +
  72         expected +
  73         "' and '" +
  74         actual +
  75         "'): " +
  76         description
  77     );
  78   }
  79 }
  80
  81 /**
  82  * Compare given values which are same format of
  83  * KeyframeEffectReadonly::GetProperties.
  84  */
  85 function assert_properties_equal(actual, expected) {
  86   assert_equals(actual.length, expected.length);
  87
  88   const compareProperties = (a, b) =>
  89     a.property == b.property ? 0 : a.property < b.property ? -1 : 1;
  90
  91   const sortedActual = actual.sort(compareProperties);
  92   const sortedExpected = expected.sort(compareProperties);
  93
  94   const serializeValues = values =>
  95     values
  96       .map(
  97         value =>
  98           "{ " +
  99           ["offset", "value", "easing", "composite"]
 100             .map(member => `${member}: ${value[member]}`)
 101             .join(", ") +
 102           " }"
 103       )
 104       .join(", ");
 105
 106   for (let i = 0; i < sortedActual.length; i++) {
 107     assert_equals(
 108       sortedActual[i].property,
 109       sortedExpected[i].property,
 110       "CSS property name should match"
 111     );
 112     assert_equals(
 113       serializeValues(sortedActual[i].values),
 114       serializeValues(sortedExpected[i].values),
 115       `Values arrays do not match for ` + `${sortedActual[i].property} property`
 116     );
 117   }
 118 }
 119
 120 /**
 121  * Construct a object which is same to a value of
 122  * KeyframeEffectReadonly::GetProperties().
 123  * The method returns undefined as a value in case of missing keyframe.
 124  * Therefor, we can use undefined for |value| and |easing| parameter.
 125  * @param offset - keyframe offset. e.g. 0.1
 126  * @param value - any keyframe value. e.g. undefined '1px', 'center', 0.5
 127  * @param composite - 'replace', 'add', 'accumulate'
 128  * @param easing - e.g. undefined, 'linear', 'ease' and so on
 129  * @return Object -
 130  *   e.g. { offset: 0.1, value: '1px', composite: 'replace', easing: 'ease'}
 131  */
 132 function valueFormat(offset, value, composite, easing) {
 133   return { offset, value, easing, composite };
 134 }
 135
 136 /**
 137  * Appends a div to the document body and creates an animation on the div.
 138  * NOTE: This function asserts when trying to create animations with durations
 139  * shorter than 100s because the shorter duration may cause intermittent
 140  * failures.  If you are not sure how long it is suitable, use 100s; it's
 141  * long enough but shorter than our test framework timeout (330s).
 142  * If you really need to use shorter durations, use animate() function directly.
 143  *
 144  * @param t  The testharness.js Test object. If provided, this will be used
 145  *           to register a cleanup callback to remove the div when the test
 146  *           finishes.
 147  * @param attrs  A dictionary object with attribute names and values to set on
 148  *               the div.
 149  * @param frames  The keyframes passed to Element.animate().
 150  * @param options  The options passed to Element.animate().
 151  */
 152 function addDivAndAnimate(t, attrs, frames, options) {
 153   let animDur = typeof options === "object" ? options.duration : options;
 154   assert_greater_than_equal(
 155     animDur,
 156     100 * MS_PER_SEC,
 157     "Clients of this addDivAndAnimate API must request a duration " +
 158       "of at least 100s, to avoid intermittent failures from e.g." +
 159       "the main thread being busy for an extended period"
 160   );
 161
 162   return addDiv(t, attrs).animate(frames, options);
 163 }
 164
 165 /**
 166  * Appends a div to the document body.
 167  *
 168  * @param t  The testharness.js Test object. If provided, this will be used
 169  *           to register a cleanup callback to remove the div when the test
 170  *           finishes.
 171  *
 172  * @param attrs  A dictionary object with attribute names and values to set on
 173  *               the div.
 174  */
 175 function addDiv(t, attrs) {
 176   var div = document.createElement("div");
 177   if (attrs) {
 178     for (var attrName in attrs) {
 179       div.setAttribute(attrName, attrs[attrName]);
 180     }
 181   }
 182   document.body.appendChild(div);
 183   if (t && typeof t.add_cleanup === "function") {
 184     t.add_cleanup(function () {
 185       if (div.parentNode) {
 186         div.remove();
 187       }
 188     });
 189   }
 190   return div;
 191 }
 192
 193 /**
 194  * Appends a style div to the document head.
 195  *
 196  * @param t  The testharness.js Test object. If provided, this will be used
 197  *           to register a cleanup callback to remove the style element
 198  *           when the test finishes.
 199  *
 200  * @param rules  A dictionary object with selector names and rules to set on
 201  *               the style sheet.
 202  */
 203 function addStyle(t, rules) {
 204   var extraStyle = document.createElement("style");
 205   document.head.appendChild(extraStyle);
 206   if (rules) {
 207     var sheet = extraStyle.sheet;
 208     for (var selector in rules) {
 209       sheet.insertRule(
 210         selector + "{" + rules[selector] + "}",
 211         sheet.cssRules.length
 212       );
 213     }
 214   }
 215
 216   if (t && typeof t.add_cleanup === "function") {
 217     t.add_cleanup(function () {
 218       extraStyle.remove();
 219     });
 220   }
 221 }
 222
 223 /**
 224  * Takes a CSS property (e.g. margin-left) and returns the equivalent IDL
 225  * name (e.g. marginLeft).
 226  */
 227 function propertyToIDL(property) {
 228   var prefixMatch = property.match(/^-(\w+)-/);
 229   if (prefixMatch) {
 230     var prefix = prefixMatch[1] === "moz" ? "Moz" : prefixMatch[1];
 231     property = prefix + property.substring(prefixMatch[0].length - 1);
 232   }
 233   // https://drafts.csswg.org/cssom/#css-property-to-idl-attribute
 234   return property.replace(/-([a-z])/gi, function (str, group) {
 235     return group.toUpperCase();
 236   });
 237 }
 238
 239 /**
 240  * Promise wrapper for requestAnimationFrame.
 241  */
 242 function waitForFrame() {
 243   return new Promise(function (resolve, reject) {
 244     window.requestAnimationFrame(resolve);
 245   });
 246 }
 247
 248 /**
 249  * Waits for a requestAnimationFrame callback in the next refresh driver tick.
 250  */
 251 function waitForNextFrame(aWindow = window) {
 252   const timeAtStart = aWindow.document.timeline.currentTime;
 253   return new Promise(resolve => {
 254     aWindow.requestAnimationFrame(() => {
 255       if (timeAtStart === aWindow.document.timeline.currentTime) {
 256         aWindow.requestAnimationFrame(resolve);
 257       } else {
 258         resolve();
 259       }
 260     });
 261   });
 262 }
 263
 264 /**
 265  * Returns a Promise that is resolved after the given number of consecutive
 266  * animation frames have occured (using requestAnimationFrame callbacks).
 267  *
 268  * @param aFrameCount  The number of animation frames.
 269  * @param aOnFrame  An optional function to be processed in each animation frame.
 270  * @param aWindow  An optional window object to be used for requestAnimationFrame.
 271  */
 272 function waitForAnimationFrames(aFrameCount, aOnFrame, aWindow = window) {
 273   const timeAtStart = aWindow.document.timeline.currentTime;
 274   return new Promise(function (resolve, reject) {
 275     function handleFrame() {
 276       if (aOnFrame && typeof aOnFrame === "function") {
 277         aOnFrame();
 278       }
 279       if (
 280         timeAtStart != aWindow.document.timeline.currentTime &&
 281         --aFrameCount <= 0
 282       ) {
 283         resolve();
 284       } else {
 285         aWindow.requestAnimationFrame(handleFrame); // wait another frame
 286       }
 287     }
 288     aWindow.requestAnimationFrame(handleFrame);
 289   });
 290 }
 291
 292 /**
 293  * Promise wrapper for requestIdleCallback.
 294  */
 295 function waitForIdle() {
 296   return new Promise(resolve => {
 297     requestIdleCallback(resolve);
 298   });
 299 }
 300
 301 /**
 302  * Wrapper that takes a sequence of N animations and returns:
 303  *
 304  *   Promise.all([animations[0].ready, animations[1].ready, ... animations[N-1].ready]);
 305  */
 306 function waitForAllAnimations(animations) {
 307   return Promise.all(
 308     animations.map(function (animation) {
 309       return animation.ready;
 310     })
 311   );
 312 }
 313
 314 /**
 315  * Flush the computed style for the given element. This is useful, for example,
 316  * when we are testing a transition and need the initial value of a property
 317  * to be computed so that when we synchronouslyet set it to a different value
 318  * we actually get a transition instead of that being the initial value.
 319  */
 320 function flushComputedStyle(elem) {
 321   var cs = getComputedStyle(elem);
 322   cs.marginLeft;
 323 }
 324
 325 if (opener) {
 326   for (var funcName of [
 327     "async_test",
 328     "assert_not_equals",
 329     "assert_equals",
 330     "assert_approx_equals",
 331     "assert_less_than",
 332     "assert_less_than_equal",
 333     "assert_greater_than",
 334     "assert_between_inclusive",
 335     "assert_true",
 336     "assert_false",
 337     "assert_class_string",
 338     "assert_throws",
 339     "assert_unreached",
 340     "assert_regexp_match",
 341     "promise_test",
 342     "test",
 343   ]) {
 344     if (opener[funcName]) {
 345       window[funcName] = opener[funcName].bind(opener);
 346     }
 347   }
 348
 349   window.EventWatcher = opener.EventWatcher;
 350
 351   function done() {
 352     opener.add_completion_callback(function () {
 353       self.close();
 354     });
 355     opener.done();
 356   }
 357 }
 358
 359 /*
 360  * Returns a promise that is resolved when the document has finished loading.
 361  */
 362 function waitForDocumentLoad() {
 363   return new Promise(function (resolve, reject) {
 364     if (document.readyState === "complete") {
 365       resolve();
 366     } else {
 367       window.addEventListener("load", resolve);
 368     }
 369   });
 370 }
 371
 372 /*
 373  * Enters test refresh mode, and restores the mode when |t| finishes.
 374  */
 375 function useTestRefreshMode(t) {
 376   function ensureNoSuppressedPaints() {
 377     return new Promise(resolve => {
 378       function checkSuppressedPaints() {
 379         if (!SpecialPowers.DOMWindowUtils.paintingSuppressed) {
 380           resolve();
 381         } else {
 382           window.requestAnimationFrame(checkSuppressedPaints);
 383         }
 384       }
 385       checkSuppressedPaints();
 386     });
 387   }
 388
 389   return ensureNoSuppressedPaints().then(() => {
 390     SpecialPowers.DOMWindowUtils.advanceTimeAndRefresh(0);
 391     t.add_cleanup(() => {
 392       SpecialPowers.DOMWindowUtils.restoreNormalRefresh();
 393     });
 394   });
 395 }
 396
 397 /**
 398  * Returns true if off-main-thread animations.
 399  */
 400 function isOMTAEnabled() {
 401   const OMTAPrefKey = "layers.offmainthreadcomposition.async-animations";
 402   return (
 403     SpecialPowers.DOMWindowUtils.layerManagerRemote &&
 404     SpecialPowers.getBoolPref(OMTAPrefKey)
 405   );
 406 }
 407
 408 /**
 409  * Append an SVG element to the target element.
 410  *
 411  * @param target The element which want to append.
 412  * @param attrs  A array object with attribute name and values to set on
 413  *               the SVG element.
 414  * @return An SVG outer element.
 415  */
 416 function addSVGElement(target, tag, attrs) {
 417   if (!target) {
 418     return null;
 419   }
 420   var element = document.createElementNS("http://www.w3.org/2000/svg", tag);
 421   if (attrs) {
 422     for (var attrName in attrs) {
 423       element.setAttributeNS(null, attrName, attrs[attrName]);
 424     }
 425   }
 426   target.appendChild(element);
 427   return element;
 428 }
 429
 430 /*
 431  * Get Animation distance between two specified values for a specific property.
 432  *
 433  * @param target The target element.
 434  * @param prop The CSS property.
 435  * @param v1 The first property value.
 436  * @param v2 The Second property value.
 437  *
 438  * @return The distance between |v1| and |v2| for |prop| on |target|.
 439  */
 440 function getDistance(target, prop, v1, v2) {
 441   if (!target) {
 442     return 0.0;
 443   }
 444   return SpecialPowers.DOMWindowUtils.computeAnimationDistance(
 445     target,
 446     prop,
 447     v1,
 448     v2
 449   );
 450 }
 451
 452 /*
 453  * A promise wrapper for waiting MozAfterPaint.
 454  */
 455 function waitForPaints() {
 456   // FIXME: Bug 1415065. Instead waiting for two requestAnimationFrames, we
 457   // should wait for MozAfterPaint once after MozAfterPaint is fired properly
 458   // (bug 1341294).
 459   return waitForAnimationFrames(2);
 460 }
 461
 462 // Returns true if |aAnimation| begins at the current timeline time.  We
 463 // sometimes need to detect this case because if we started an animation
 464 // asynchronously (e.g. using play()) and then ended up running the next frame
 465 // at precisely the time the animation started (due to aligning with vsync
 466 // refresh rate) then we won't end up restyling in that frame.
 467 function animationStartsRightNow(aAnimation) {
 468   return (
 469     aAnimation.startTime === aAnimation.timeline.currentTime &&
 470     aAnimation.currentTime === 0
 471   );
 472 }
 473
 474 // Waits for a given animation being ready to restyle.
 475 async function waitForAnimationReadyToRestyle(aAnimation) {
 476   await aAnimation.ready;
 477   // If |aAnimation| begins at the current timeline time, we will not process
 478   // restyling in the initial frame because of aligning with the refresh driver,
 479   // the animation frame in which the ready promise is resolved happens to
 480   // coincide perfectly with the start time of the animation.  In this case no
 481   // restyling is needed in the frame so we have to wait one more frame.
 482   if (animationStartsRightNow(aAnimation)) {
 483     await waitForNextFrame(aAnimation.ownerGlobal);
 484   }
 485 }
 486
 487 // Returns the animation restyle markers observed during |frameCount| refresh
 488 // driver ticks in this `window`.  This function is typically used to count the
 489 // number of restyles that take place as part of the style update that happens
 490 // on each refresh driver tick, as opposed to synchronous restyles triggered by
 491 // script.
 492 //
 493 // For the latter observeAnimSyncStyling (below) should be used.
 494 function observeStyling(frameCount, onFrame) {
 495   return observeStylingInTargetWindow(window, frameCount, onFrame);
 496 }
 497
 498 // As with observeStyling but applied to target window |aWindow|.
 499 function observeStylingInTargetWindow(aWindow, aFrameCount, aOnFrame) {
 500   let priorAnimationTriggeredRestyles =
 501     SpecialPowers.wrap(aWindow).windowUtils.animationTriggeredRestyles;
 502
 503   return new Promise(resolve => {
 504     return waitForAnimationFrames(aFrameCount, aOnFrame, aWindow).then(() => {
 505       let restyleCount =
 506         SpecialPowers.wrap(aWindow).windowUtils.animationTriggeredRestyles -
 507         priorAnimationTriggeredRestyles;
 508
 509       resolve(restyleCount);
 510     });
 511   });
 512 }