Bug 1400225 - Subscribe to and relay web content DOM events. r=automatedtester,whimboo

This makes it possible to subscribe to DOM events in web content, in
order to facilitate fixes for cases such as https://bugzil.la/1397007.

Although the current interface, WebElementEventTarget, is associated with
browser.Context (curBrowser) it is the intention that we in the future
will associate this with representations of the marshaled web element.
This will make it quack and act like an Element's EventTarget, which
has nice parity to it.

The WebElementEventTarget works by passing IPC messages to
a backend service in the content frame script implemented by
ContentEventObserverService.  This registers event handlers for specific
DOM events, and relays these events back to the browser-specific message
handler in chrome.

This will enable chrome code to wait for events to occur in content,
like this:

	await new Promise(resolve => {
	  webElement.addEventListener("visibilitychange", resolve, {once: true});
	  contentBrowser.minimize();
	});

MozReview-Commit-ID: B8MMHyG8n04

--HG--
extra : rebase_source : 25ac77fbcfb09435325719ac61614c4a8ce37996

testing/marionette/browser.js

@@ -7,6 +7,7 @@
 
 const {utils: Cu} = Components;
 
+const {WebElementEventTarget} = Cu.import("chrome://marionette/content/dom.js", {});
 Cu.import("chrome://marionette/content/element.js");
 const {
   NoSuchWindowError,
@@ -137,6 +138,10 @@ browser.Context = class {
     return null;
   }
 
+  get messageManager() {
+    return this.contentBrowser.messageManager;
+  }
+
   /**
    * The current frame ID is managed per browser element on desktop in
    * case the ID needs to be refreshed. The currently selected window is
@@ -331,6 +336,10 @@ browser.Context = class {
         }
       }
     }
+
+    // TODO(ato): Currently tied to curBrowser, but should be moved to
+    // WebElement when introduced by https://bugzil.la/1400256.
+    this.eventObserver = new WebElementEventTarget(this.messageManager);
   }
 
   /**

testing/marionette/dom.js

@@ -0,0 +1,203 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this file,
+ * You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+"use strict";
+
+const {utils: Cu} = Components;
+
+this.EXPORTED_SYMBOLS = [
+  "ContentEventObserverService",
+  "WebElementEventTarget",
+];
+
+/**
+ * The {@link EventTarget} for web elements can be used to observe DOM
+ * events in the content document.
+ *
+ * A caveat of the current implementation is that it is only possible
+ * to listen for top-level <code>window</code> global events.
+ *
+ * It needs to be backed by a {@link ContentEventObserverService} in a
+ * content frame script.
+ *
+ * Usage:
+ *
+ * <pre><code>
+ *     let observer = new WebElementEventTarget(messageManager);
+ *     await new Promise(resolve => {
+ *       observer.addEventListener("visibilitychange", resolve, {once: true});
+ *       chromeWindow.minimize();
+ *     });
+ * </code></pre>
+ */
+class WebElementEventTarget {
+  /**
+   * @param {function(): nsIMessageListenerManager} messageManagerFn
+   *     Message manager to the current browser.
+   */
+  constructor(messageManager) {
+    this.mm = messageManager;
+    this.listeners = {};
+    this.mm.addMessageListener("Marionette:DOM:OnEvent", this);
+  }
+
+  /**
+   * Register an event handler of a specific event type from the content
+   * frame.
+   *
+   * @param {string} type
+   *     Event type to listen for.
+   * @param {EventListener} listener
+   *     Object which receives a notification (a {@link BareEvent})
+   *     when an event of the specified type occurs.  This must be
+   *     an object implementing the {@link EventListener} interface,
+   *     or a JavaScript function.
+   * @param {boolean=} once
+   *     Indicates that the <var>listener</var> should be invoked at
+   *     most once after being added.  If true, the <var>listener</var>
+   *     would automatically be removed when invoked.
+   */
+  addEventListener(type, listener, {once = false} = {}) {
+    if (!(type in this.listeners)) {
+      this.listeners[type] = [];
+    }
+
+    if (!this.listeners[type].includes(listener)) {
+      listener.once = once;
+      this.listeners[type].push(listener);
+    }
+
+    this.mm.sendAsyncMessage("Marionette:DOM:AddEventListener", {type});
+  }
+
+  /**
+   * Removes an event listener.
+   *
+   * @param {string} type
+   *     Type of event to cease listening for.
+   * @param {EventListener} listener
+   *     Event handler to remove from the event target.
+   */
+  removeEventListener(type, listener) {
+    if (!(type in this.listeners)) {
+      return;
+    }
+
+    let stack = this.listeners[type];
+    for (let i = stack.length - 1; i >= 0; --i) {
+      if (stack[i] === listener) {
+        stack.splice(i, 1);
+        if (stack.length == 0) {
+          this.mm.sendAsyncMessage("Marionette:DOM:RemoveEventListener", {type});
+        }
+        return;
+      }
+    }
+  }
+
+  dispatchEvent(event) {
+    if (!(event.type in this.listeners)) {
+      return;
+    }
+
+    event.target = this;
+
+    let stack = this.listeners[event.type].slice(0);
+    stack.forEach(listener => {
+      listener.call(this, event);
+
+      if (listener.once) {
+        this.removeEventListener(event.type, listener);
+      }
+    });
+  }
+
+  receiveMessage({target, name, data, objects}) {
+    if (name != "Marionette:DOM:OnEvent") {
+      return;
+    }
+
+    let ev = {
+      type: data.type,
+      target: objects.target,
+    };
+    this.dispatchEvent(ev);
+  }
+}
+this.WebElementEventTarget = WebElementEventTarget;
+
+/**
+ * Provides the frame script backend for the
+ * {@link WebElementEventTarget}.
+ *
+ * This service receives requests for new DOM events to listen for and
+ * to cease listening for, and despatches IPC messages to the browser
+ * when they fire.
+ */
+class ContentEventObserverService {
+  /**
+   * @param {WindowProxy} windowGlobal
+   *     Window.
+   * @param {nsIMessageSender.sendAsyncMessage} sendAsyncMessage
+   *     Function for sending an async message to the parent browser.
+   */
+  constructor(windowGlobal, sendAsyncMessage) {
+    this.window = windowGlobal;
+    this.sendAsyncMessage = sendAsyncMessage;
+    this.events = new Set();
+  }
+
+  /**
+   * Observe a new DOM event.
+   *
+   * When the DOM event of <var>type</var> fires, a message is passed
+   * to the parent browser's event observer.
+   *
+   * If event type is already being observed, only a single message
+   * is sent.  E.g. multiple registration for events will only ever emit
+   * a maximum of one message.
+   *
+   * @param {string} type
+   *     DOM event to listen for.
+   */
+  add(type) {
+    if (this.events.has(type)) {
+      return;
+    }
+    this.window.addEventListener(type, this);
+    this.events.add(type);
+  }
+
+  /**
+   * Ceases observing a DOM event.
+   *
+   * @param {string} type
+   *     DOM event to stop listening for.
+   */
+  remove(type) {
+    if (!this.events.has(type)) {
+      return;
+    }
+    this.window.removeEventListener(type, this);
+    this.events.delete(type);
+  }
+
+  /** Ceases observing all previously registered DOM events. */
+  clear() {
+    for (let ev of this) {
+      this.remove(ev);
+    }
+  }
+
+  * [Symbol.iterator]() {
+    for (let ev of this.events) {
+      yield ev;
+    }
+  }
+
+  handleEvent({type, target}) {
+    this.sendAsyncMessage("Marionette:DOM:OnEvent", {type}, {target});
+  }
+}
+this.ContentEventObserverService = ContentEventObserverService;

testing/marionette/jar.mn

@@ -35,6 +35,7 @@ marionette.jar:
   content/stream-utils.js (stream-utils.js)
   content/reftest.js (reftest.js)
   content/reftest.xul (reftest.xul)
+  content/dom.js (dom.js)
 #ifdef ENABLE_TESTS
   content/test.xul (chrome/test.xul)
   content/test2.xul (chrome/test2.xul)

testing/marionette/listener.js

@@ -40,6 +40,7 @@ const {
 } = Cu.import("chrome://marionette/content/error.js", {});
 Cu.import("chrome://marionette/content/evaluate.js");
 Cu.import("chrome://marionette/content/event.js");
+const {ContentEventObserverService} = Cu.import("chrome://marionette/content/dom.js", {});
 Cu.import("chrome://marionette/content/interaction.js");
 Cu.import("chrome://marionette/content/legacyaction.js");
 Cu.import("chrome://marionette/content/navigate.js");
@@ -115,6 +116,9 @@ const modalHandler = function() {
 const sandboxes = new Sandboxes(() => curContainer.frame);
 let sandboxName = "default";
 
+const eventObservers = new ContentEventObserverService(
+    content, sendAsyncMessage.bind(this));
+
 /**
  * The load listener singleton helps to keep track of active page load
  * activities, and can be used by any command which might cause a navigation
@@ -615,6 +619,8 @@ function startListeners() {
   addMessageListenerId("Marionette:sleepSession", sleepSession);
   addMessageListenerId("Marionette:takeScreenshot", takeScreenshotFn);
   addMessageListenerId("Marionette:reftestWait", reftestWaitFn);
+  addMessageListener("Marionette:DOM:AddEventListener", domAddEventListener);
+  addMessageListener("Marionette:DOM:RemoveEventListener", domRemoveEventListener);
 }
 
 /**
@@ -1906,5 +1912,13 @@ async function reftestWait(url, remote) {
   }
 }
 
+function domAddEventListener(msg) {
+  eventObservers.add(msg.json.type);
+}
+
+function domRemoveEventListener(msg) {
+  eventObservers.remove(msg.json.type);
+}
+
 // Call register self when we get loaded
 registerSelf();

testing/marionette/test_dom.js

@@ -0,0 +1,278 @@
+const {utils: Cu} = Components;
+
+const {
+  ContentEventObserverService,
+  WebElementEventTarget,
+} = Cu.import("chrome://marionette/content/dom.js", {});
+
+class MessageSender {
+  constructor() {
+    this.listeners = {};
+    this.sent = [];
+  }
+
+  addMessageListener(name, listener) {
+    this.listeners[name] = listener;
+  }
+
+  sendAsyncMessage(name, data, objects) {
+    this.sent.push({name, data, objects});
+  }
+}
+
+class Window {
+  constructor() {
+    this.events = [];
+  }
+
+  addEventListener(type, listener) {
+    this.events.push(type);
+  }
+
+  removeEventListener(type, listener) {
+    for (let i = 0; i < this.events.length; ++i) {
+      if (this.events[i] === type) {
+        this.events.splice(i, 1);
+        return;
+      }
+    }
+  }
+}
+
+add_test(function test_WebElementEventTarget_addEventListener_init() {
+  let ipc = new MessageSender();
+  let eventTarget = new WebElementEventTarget(ipc);
+  equal(Object.keys(eventTarget.listeners).length, 0);
+  equal(Object.keys(ipc.listeners).length, 1);
+
+  run_next_test();
+});
+
+add_test(function test_addEventListener() {
+  let ipc = new MessageSender();
+  let eventTarget = new WebElementEventTarget(ipc);
+
+  let listener = () => {};
+  eventTarget.addEventListener("click", listener);
+
+  // click listener was appended
+  equal(Object.keys(eventTarget.listeners).length, 1);
+  ok("click" in eventTarget.listeners);
+  equal(eventTarget.listeners["click"].length, 1);
+  equal(eventTarget.listeners["click"][0], listener);
+
+  // should have sent a registration message
+  deepEqual(
+      ipc.sent[0], {
+        name: "Marionette:DOM:AddEventListener",
+        data: {type: "click"},
+        objects: undefined,
+      });
+
+  run_next_test();
+});
+
+add_test(function test_addEventListener_sameReference() {
+  let ipc = new MessageSender();
+  let eventTarget = new WebElementEventTarget(ipc);
+
+  let listener = () => {};
+  eventTarget.addEventListener("click", listener);
+  eventTarget.addEventListener("click", listener);
+  equal(eventTarget.listeners["click"].length, 1);
+
+  run_next_test();
+});
+
+add_test(function test_WebElementEventTarget_addEventListener_once() {
+  let ipc = new MessageSender();
+  let eventTarget = new WebElementEventTarget(ipc);
+
+  eventTarget.addEventListener("click", () => {}, {once: true});
+  equal(eventTarget.listeners["click"][0].once, true);
+
+  eventTarget.dispatchEvent({type: "click"});
+  equal(eventTarget.listeners["click"].length, 0);
+  deepEqual(
+      ipc.sent[1], {
+        name: "Marionette:DOM:RemoveEventListener",
+        data: {type: "click"},
+        objects: undefined,
+      });
+
+  run_next_test();
+});
+
+add_test(function test_WebElementEventTarget_removeEventListener() {
+  let ipc = new MessageSender();
+  let eventTarget = new WebElementEventTarget(ipc);
+
+  equal(Object.keys(eventTarget.listeners).length, 0);
+  eventTarget.removeEventListener("click", () => {});
+  equal(Object.keys(eventTarget.listeners).length, 0);
+
+  let firstListener = () => {};
+  eventTarget.addEventListener("click", firstListener);
+  equal(eventTarget.listeners["click"].length, 1);
+  ok(eventTarget.listeners["click"][0] === firstListener);
+
+  let secondListener = () => {};
+  eventTarget.addEventListener("click", secondListener);
+  equal(eventTarget.listeners["click"].length, 2);
+  ok(eventTarget.listeners["click"][1] === secondListener);
+
+  ok(eventTarget.listeners["click"][0] !== eventTarget.listeners["click"][1]);
+
+  eventTarget.removeEventListener("click", secondListener);
+  equal(eventTarget.listeners["click"].length, 1);
+  ok(eventTarget.listeners["click"][0] === firstListener);
+
+  // event should not have been unregistered
+  // because there still exists another click event
+  equal(ipc.sent[ipc.sent.length - 1].name, "Marionette:DOM:AddEventListener");
+
+  eventTarget.removeEventListener("click", firstListener);
+  equal(eventTarget.listeners["click"].length, 0);
+  deepEqual(
+      ipc.sent[ipc.sent.length - 1],
+      {
+        name: "Marionette:DOM:RemoveEventListener",
+        data: {type: "click"},
+        objects: undefined,
+      });
+
+  run_next_test();
+});
+
+add_test(function test_WebElementEventTarget_dispatchEvent() {
+  let ipc = new MessageSender();
+  let eventTarget = new WebElementEventTarget(ipc);
+
+  let listenerCalled = false;
+  let listener = () => listenerCalled = true;
+  eventTarget.addEventListener("click", listener);
+  eventTarget.dispatchEvent({type: "click"});
+  ok(listenerCalled);
+
+  run_next_test();
+});
+
+add_test(function test_WebElementEventTarget_dispatchEvent_multipleListeners() {
+  let ipc = new MessageSender();
+  let eventTarget = new WebElementEventTarget(ipc);
+
+  let clicksA = 0;
+  let clicksB = 0;
+  let listenerA = () => ++clicksA;
+  let listenerB = () => ++clicksB;
+
+  // the same listener should only be added, and consequently fire, once
+  eventTarget.addEventListener("click", listenerA);
+  eventTarget.addEventListener("click", listenerA);
+  eventTarget.addEventListener("click", listenerB);
+  eventTarget.dispatchEvent({type: "click"});
+  equal(clicksA, 1);
+  equal(clicksB, 1);
+
+  run_next_test();
+});
+
+add_test(function test_ContentEventObserverService_add() {
+  let ipc = new MessageSender();
+  let win = new Window();
+  let obs = new ContentEventObserverService(
+      win, ipc.sendAsyncMessage.bind(ipc));
+
+  equal(obs.events.size, 0);
+  equal(win.events.length, 0);
+
+  obs.add("foo");
+  equal(obs.events.size, 1);
+  equal(win.events.length, 1);
+  equal(obs.events.values().next().value, "foo");
+  equal(win.events[0], "foo");
+
+  obs.add("foo");
+  equal(obs.events.size, 1);
+  equal(win.events.length, 1);
+
+  run_next_test();
+});
+
+add_test(function test_ContentEventObserverService_remove() {
+  let ipc = new MessageSender();
+  let win = new Window();
+  let obs = new ContentEventObserverService(
+      win, ipc.sendAsyncMessage.bind(ipc));
+
+  obs.remove("foo");
+  equal(obs.events.size, 0);
+  equal(win.events.length, 0);
+
+  obs.add("bar");
+  equal(obs.events.size, 1);
+  equal(win.events.length, 1);
+
+  obs.remove("bar");
+  equal(obs.events.size, 0);
+  equal(win.events.length, 0);
+
+  obs.add("baz");
+  obs.add("baz");
+  equal(obs.events.size, 1);
+  equal(win.events.length, 1);
+
+  obs.add("bah");
+  equal(obs.events.size, 2);
+  equal(win.events.length, 2);
+
+  obs.remove("baz");
+  equal(obs.events.size, 1);
+  equal(win.events.length, 1);
+
+  obs.remove("bah");
+  equal(obs.events.size, 0);
+  equal(win.events.length, 0);
+
+  run_next_test();
+});
+
+add_test(function test_ContentEventObserverService_clear() {
+  let ipc = new MessageSender();
+  let win = new Window();
+  let obs = new ContentEventObserverService(
+      win, ipc.sendAsyncMessage.bind(ipc));
+
+  obs.clear();
+  equal(obs.events.size, 0);
+  equal(win.events.length, 0);
+
+  obs.add("foo");
+  obs.add("foo");
+  obs.add("bar");
+  equal(obs.events.size, 2);
+  equal(win.events.length, 2);
+
+  obs.clear();
+  equal(obs.events.size, 0);
+  equal(win.events.length, 0);
+
+  run_next_test();
+});
+
+add_test(function test_ContentEventObserverService_handleEvent() {
+  let ipc = new MessageSender();
+  let win = new Window();
+  let obs = new ContentEventObserverService(
+      win, ipc.sendAsyncMessage.bind(ipc));
+
+  obs.handleEvent({type: "click", target: win});
+  deepEqual(
+      ipc.sent[0], {
+        name: "Marionette:DOM:OnEvent",
+        data: {type: "click"},
+        objects: {"target": win},
+      });
+
+  run_next_test();
+});

testing/marionette/unit.ini

@@ -10,6 +10,7 @@ skip-if = appname == "thunderbird"
 [test_action.js]
 [test_assert.js]
 [test_cookie.js]
+[test_dom.js]
 [test_element.js]
 [test_error.js]
 [test_message.js]