Bug 936273 - [Australis] UITour: Allow page to specify which highlight animation to use. r=Unfocused

browser/modules/UITour.jsm

@@ -30,7 +30,7 @@ this.UITour = {
   urlbarCapture: new WeakMap(),
   appMenuOpenForAnnotation: new Set(),
 
-  highlightEffects: ["wobble", "zoom", "color"],
+  highlightEffects: ["random", "wobble", "zoom", "color"],
   targets: new Map([
     ["addons",      {query: "#add-ons-button"}],
     ["appMenu",     {query: "#PanelUI-menu-button"}],
@@ -104,7 +104,11 @@ this.UITour = {
             Cu.reportError("UITour: Target could not be resolved: " + data.target);
             return;
           }
-          this.showHighlight(target);
+          let effect = undefined;
+          if (this.highlightEffects.indexOf(data.effect) !== -1) {
+            effect = data.effect;
+          }
+          this.showHighlight(target, effect);
         }).then(null, Cu.reportError);
         break;
       }
@@ -442,14 +446,24 @@ this.UITour = {
       aWindow.gBrowser.removeTab(tabInfo.tab);
   },
 
-  showHighlight: function(aTarget) {
+  /**
+   * @param aTarget    The element to highlight.
+   * @param aEffect    (optional) The effect to use from UITour.highlightEffects or "none".
+   * @see UITour.highlightEffects
+   */
+  showHighlight: function(aTarget, aEffect = "none") {
     function showHighlightPanel(aTargetEl) {
       let highlighter = aTargetEl.ownerDocument.getElementById("UITourHighlight");
 
-      let randomEffect = Math.floor(Math.random() * this.highlightEffects.length);
-      if (randomEffect == this.highlightEffects.length)
-        randomEffect--; // On the order of 1 in 2^62 chance of this happening.
-      highlighter.setAttribute("active", this.highlightEffects[randomEffect]);
+      let effect = aEffect;
+      if (effect == "random") {
+        // Exclude "random" from the randomly selected effects.
+        let randomEffect = 1 + Math.floor(Math.random() * (this.highlightEffects.length - 1));
+        if (randomEffect == this.highlightEffects.length)
+          randomEffect--; // On the order of 1 in 2^62 chance of this happening.
+        effect = this.highlightEffects[randomEffect];
+      }
+      highlighter.setAttribute("active", effect);
 
       let targetRect = aTargetEl.getBoundingClientRect();
 

browser/modules/test/browser_UITour.js

@@ -225,6 +225,62 @@ let tests = [
       }, "Highlight should move to the appMenu button");
     }, "Highlight should be shown after showHighlight() for fixed panel items");
   },
+  function test_highlight_effect(done) {
+    function waitForHighlightWithEffect(highlightEl, effect, next, error) {
+      return waitForCondition(() => highlightEl.getAttribute("active") == effect,
+                              next,
+                              error);
+    }
+    function checkDefaultEffect() {
+      is(highlight.getAttribute("active"), "none", "The default should be no effect");
+
+      gContentAPI.showHighlight("urlbar", "none");
+      waitForHighlightWithEffect(highlight, "none", checkZoomEffect, "There should be no effect");
+    }
+    function checkZoomEffect() {
+      gContentAPI.showHighlight("urlbar", "zoom");
+      waitForHighlightWithEffect(highlight, "zoom", () => {
+        let style = window.getComputedStyle(highlight);
+        is(style.animationName, "uitour-zoom", "The animation-name should be uitour-zoom");
+        checkRandomEffect();
+      }, "There should be a zoom effect");
+    }
+    function checkRandomEffect() {
+      function waitForActiveHighlight(highlightEl, next, error) {
+        return waitForCondition(() => highlightEl.hasAttribute("active"),
+                                next,
+                                error);
+      }
+
+      gContentAPI.hideHighlight();
+      gContentAPI.showHighlight("urlbar", "random");
+      waitForActiveHighlight(highlight, () => {
+        ok(highlight.hasAttribute("active"), "The highlight should be active");
+        isnot(highlight.getAttribute("active"), "none", "A random effect other than none should have been chosen");
+        isnot(highlight.getAttribute("active"), "random", "The random effect shouldn't be 'random'");
+        isnot(UITour.highlightEffects.indexOf(highlight.getAttribute("active")), -1, "Check that a supported effect was randomly chosen");
+        done();
+      }, "There should be an active highlight with a random effect");
+    }
+
+    let highlight = document.getElementById("UITourHighlight");
+    is_element_hidden(highlight, "Highlight should initially be hidden");
+
+    gContentAPI.showHighlight("urlbar");
+    waitForElementToBeVisible(highlight, checkDefaultEffect, "Highlight should be shown after showHighlight()");
+  },
+  function test_highlight_effect_unsupported(done) {
+    function checkUnsupportedEffect() {
+      is(highlight.getAttribute("active"), "none", "No effect should be used when an unsupported effect is requested");
+      done();
+    }
+
+    let highlight = document.getElementById("UITourHighlight");
+    is_element_hidden(highlight, "Highlight should initially be hidden");
+
+    gContentAPI.showHighlight("urlbar", "__UNSUPPORTED__");
+    waitForElementToBeVisible(highlight, checkUnsupportedEffect, "Highlight should be shown after showHighlight()");
+  },
   function test_info_1(done) {
     let popup = document.getElementById("UITourTooltip");
     let title = document.getElementById("UITourTooltipTitle");

browser/modules/test/uitour.js

@@ -40,9 +40,10 @@ if (typeof Mozilla == 'undefined') {
 
 	Mozilla.UITour.DEFAULT_THEME_CYCLE_DELAY = 10 * 1000;
 
-	Mozilla.UITour.showHighlight = function(target) {
+	Mozilla.UITour.showHighlight = function(target, effect) {
 		_sendEvent('showHighlight', {
-			target: target
+			target: target,
+			effect: effect
 		});
 	};