tor-browser

testdriver-actions.js (19165B)

---

(function() {
 let sourceNameIdx = 0;

 /**
  * @class
  * Builder for creating a sequence of actions
  *
  *
  * The actions are dispatched once
  * :js:func:`test_driver.Actions.send` is called. This returns a
  * promise which resolves once the actions are complete.
  *
  * The other methods on :js:class:`test_driver.Actions` object are
  * used to build the sequence of actions that will be sent. These
  * return the `Actions` object itself, so the actions sequence can
  * be constructed by chaining method calls.
  *
  * Internally :js:func:`test_driver.Actions.send` invokes
  * :js:func:`test_driver.action_sequence`.
  *
  * @example
  * let text_box = document.getElementById("text");
  *
  * let actions = new test_driver.Actions()
  *    .pointerMove(0, 0, {origin: text_box})
  *    .pointerDown()
  *    .pointerUp()
  *    .addTick()
  *    .keyDown("p")
  *    .keyUp("p");
  *
  * await actions.send();
  *
  * @param {number} [defaultTickDuration] - The default duration of a
  * tick. Be default this is set ot 16ms, which is one frame time
  * based on 60Hz display.
  */
 function Actions(defaultTickDuration=16) {
   this.sourceTypes = new Map([["key", KeySource],
                               ["pointer", PointerSource],
                               ["wheel", WheelSource],
                               ["none", GeneralSource]]);
   this.sources = new Map();
   this.sourceOrder = [];
   for (let sourceType of this.sourceTypes.keys()) {
     this.sources.set(sourceType, new Map());
   }
   this.currentSources = new Map();
   for (let sourceType of this.sourceTypes.keys()) {
     this.currentSources.set(sourceType, null);
   }
   this.createSource("none");
   this.tickIdx = 0;
   this.defaultTickDuration = defaultTickDuration;
   this.context = null;
 }

 Actions.prototype = {
   ButtonType: {
     LEFT: 0,
     MIDDLE: 1,
     RIGHT: 2,
     BACK: 3,
     FORWARD: 4,
   },

   /**
    * Generate the action sequence suitable for passing to
    * test_driver.action_sequence
    *
    * @returns {Array} Array of WebDriver-compatible actions sequences
    */
   serialize: function() {
     let actions = [];
     for (let [sourceType, sourceName] of this.sourceOrder) {
       let source = this.sources.get(sourceType).get(sourceName);
       let serialized = source.serialize(this.tickIdx + 1, this.defaultTickDuration);
       if (serialized) {
         serialized.id = sourceName;
         actions.push(serialized);
       }
     }
     return actions;
   },

   /**
    * Generate and send the action sequence
    *
    * @returns {Promise} fulfilled after the sequence is executed,
    *                    rejected if any actions fail.
    */
   send: function() {
     let actions;
     try {
       actions = this.serialize();
     } catch(e) {
       return Promise.reject(e);
     }
     return test_driver.action_sequence(actions, this.context);
   },

   /**
    * Set the context for the actions
    *
    * @param {WindowProxy} context - Context in which to run the action sequence
    */
   setContext: function(context) {
     this.context = context;
     return this;
   },

   /**
    * Get the action source with a particular source type and name.
    * If no name is passed, a new source with the given type is
    * created.
    *
    * @param {String} type - Source type ('none', 'key', 'pointer', or 'wheel')
    * @param {String?} name - Name of the source
    * @returns {Source} Source object for that source.
    */
   getSource: function(type, name) {
     if (!this.sources.has(type)) {
       throw new Error(`${type} is not a valid action type`);
     }
     if (name === null || name === undefined) {
       name = this.currentSources.get(type);
     }
     if (name === null || name === undefined) {
       return this.createSource(type, null);
     }
     return this.sources.get(type).get(name);
   },

   setSource: function(type, name) {
     if (!this.sources.has(type)) {
       throw new Error(`${type} is not a valid action type`);
     }
     if (!this.sources.get(type).has(name)) {
       throw new Error(`${name} is not a valid source for ${type}`);
     }
     this.currentSources.set(type, name);
     return this;
   },

   /**
    * Add a new key input source with the given name
    *
    * @param {String} name - Name of the key source
    * @param {Bool} set - Set source as the default key source
    * @returns {Actions}
    */
   addKeyboard: function(name, set=true) {
     this.createSource("key", name);
     if (set) {
       this.setKeyboard(name);
     }
     return this;
   },

   /**
    * Set the current default key source
    *
    * @param {String} name - Name of the key source
    * @returns {Actions}
    */
   setKeyboard: function(name) {
     this.setSource("key", name);
     return this;
   },

   /**
    * Add a new pointer input source with the given name
    *
    * @param {String} type - Name of the pointer source
    * @param {String} pointerType - Type of pointing device
    * @param {Bool} set - Set source as the default pointer source
    * @returns {Actions}
    */
   addPointer: function(name, pointerType="mouse", set=true) {
     this.createSource("pointer", name, {pointerType: pointerType});
     if (set) {
       this.setPointer(name);
     }
     return this;
   },

   /**
    * Set the current default pointer source
    *
    * @param {String} name - Name of the pointer source
    * @returns {Actions}
    */
   setPointer: function(name) {
     this.setSource("pointer", name);
     return this;
   },

   /**
    * Add a new wheel input source with the given name
    *
    * @param {String} type - Name of the wheel source
    * @param {Bool} set - Set source as the default wheel source
    * @returns {Actions}
    */
   addWheel: function(name, set=true) {
     this.createSource("wheel", name);
     if (set) {
       this.setWheel(name);
     }
     return this;
   },

   /**
    * Set the current default wheel source
    *
    * @param {String} name - Name of the wheel source
    * @returns {Actions}
    */
   setWheel: function(name) {
     this.setSource("wheel", name);
     return this;
   },

   createSource: function(type, name, parameters={}) {
     if (!this.sources.has(type)) {
       throw new Error(`${type} is not a valid action type`);
     }
     let sourceNames = new Set();
     for (let [_, name] of this.sourceOrder) {
       sourceNames.add(name);
     }
     if (!name) {
       do {
         name = "" + sourceNameIdx++;
       } while (sourceNames.has(name))
     } else {
       if (sourceNames.has(name)) {
         throw new Error(`Alreay have a source of type ${type} named ${name}.`);
       }
     }
     this.sources.get(type).set(name, new (this.sourceTypes.get(type))(parameters));
     this.currentSources.set(type, name);
     this.sourceOrder.push([type, name]);
     return this.sources.get(type).get(name);
   },

   /**
    * Insert a new actions tick
    *
    * @param {Number?} duration - Minimum length of the tick in ms.
    * @returns {Actions}
    */
   addTick: function(duration) {
     this.tickIdx += 1;
     if (duration) {
       this.pause(duration);
     }
     return this;
   },

   /**
    * Add a pause to the current tick
    *
    * @param {Number?} duration - Minimum length of the tick in ms.
    * @param {String} sourceType - source type
    * @param {String?} sourceName - Named key, pointer or wheel source to use
    *                               or null for the default key, pointer or
    *                               wheel source
    * @returns {Actions}
    */
   pause: function(duration=0, sourceType="none", {sourceName=null}={}) {
     if (sourceType=="none")
       this.getSource("none").addPause(this, duration);
     else
       this.getSource(sourceType, sourceName).addPause(this, duration);
     return this;
   },

   /**
    * Create a keyDown event for the current default key source
    *
    * To send special keys, send the respective key's codepoint,
    * as defined by `WebDriver
    * <https://w3c.github.io/webdriver/#keyboard-actions>`_.
    *
    * @param {String} key - Key to press
    * @param {String?} sourceName - Named key source to use or null for the default key source
    * @returns {Actions}
    */
   keyDown: function(key, {sourceName=null}={}) {
     let source = this.getSource("key", sourceName);
     source.keyDown(this, key);
     return this;
   },

   /**
    * Create a keyUp event for the current default key source
    *
    * To send special keys, send the respective key's codepoint,
    * as defined by `WebDriver
    * <https://w3c.github.io/webdriver/#keyboard-actions>`_.
    *
    * @param {String} key - Key to release
    * @param {String?} sourceName - Named key source to use or null for the default key source
    * @returns {Actions}
    */
   keyUp: function(key, {sourceName=null}={}) {
     let source = this.getSource("key", sourceName);
     source.keyUp(this, key);
     return this;
   },

   /**
    * Create a pointerDown event for the current default pointer source
    *
    * @param {String} button - Button to press
    * @param {String?} sourceName - Named pointer source to use or null for the default
    *                               pointer source
    * @returns {Actions}
    */
   pointerDown: function({button=this.ButtonType.LEFT, sourceName=null,
                          width, height, pressure, tangentialPressure,
                          tiltX, tiltY, twist, altitudeAngle, azimuthAngle}={}) {
     let source = this.getSource("pointer", sourceName);
     source.pointerDown(this, button, width, height, pressure, tangentialPressure,
                        tiltX, tiltY, twist, altitudeAngle, azimuthAngle);
     return this;
   },

   /**
    * Create a pointerUp event for the current default pointer source
    *
    * @param {String} button - Button to release
    * @param {String?} sourceName - Named pointer source to use or null for the default pointer
    *                               source
    * @returns {Actions}
    */
   pointerUp: function({button=this.ButtonType.LEFT, sourceName=null}={}) {
     let source = this.getSource("pointer", sourceName);
     source.pointerUp(this, button);
     return this;
   },

   /**
    * Create a move event for the current default pointer source
    *
    * @param {Number} x - Destination x coordinate
    * @param {Number} y - Destination y coordinate
    * @param {String|Element} origin - Origin of the coordinate system.
    *                                  Either "pointer", "viewport" or an Element
    * @param {Number?} duration - Time in ms for the move
    * @param {String?} sourceName - Named pointer source to use or null for the default pointer
    *                               source
    * @returns {Actions}
    */
   pointerMove: function(x, y,
                         {origin="viewport", duration, sourceName=null,
                          width, height, pressure, tangentialPressure,
                          tiltX, tiltY, twist, altitudeAngle, azimuthAngle}={}) {
     let source = this.getSource("pointer", sourceName);
     source.pointerMove(this, x, y, duration, origin, width, height, pressure,
                        tangentialPressure, tiltX, tiltY, twist, altitudeAngle,
                        azimuthAngle);
     return this;
   },

   /**
    * Create a scroll event for the current default wheel source
    *
    * @param {Number} x - mouse cursor x coordinate
    * @param {Number} y - mouse cursor y coordinate
    * @param {Number} deltaX - scroll delta value along the x-axis in pixels
    * @param {Number} deltaY - scroll delta value along the y-axis in pixels
    * @param {String|Element} origin - Origin of the coordinate system.
    *                                  Either "viewport" or an Element
    * @param {Number?} duration - Time in ms for the scroll
    * @param {String?} sourceName - Named wheel source to use or null for the
    *                               default wheel source
    * @returns {Actions}
    */
   scroll: function(x, y, deltaX, deltaY,
                    {origin="viewport", duration, sourceName=null}={}) {
     let source = this.getSource("wheel", sourceName);
     source.scroll(this, x, y, deltaX, deltaY, duration, origin);
     return this;
   },
 };

 function GeneralSource() {
   this.actions = new Map();
 }

 GeneralSource.prototype = {
   serialize: function(tickCount, defaultTickDuration) {
     let actions = [];
     let data = {"type": "none", "actions": actions};
     for (let i=0; i<tickCount; i++) {
       if (this.actions.has(i)) {
         actions.push(this.actions.get(i));
       } else {
         actions.push({"type": "pause", duration: defaultTickDuration});
       }
     }
     return data;
   },

   addPause: function(actions, duration) {
     let tick = actions.tickIdx;
     if (this.actions.has(tick)) {
       throw new Error(`Already have a pause action for the current tick`);
     }
     this.actions.set(tick, {type: "pause", duration: duration});
   },
 };

 function KeySource() {
   this.actions = new Map();
 }

 KeySource.prototype = {
   serialize: function(tickCount) {
     if (!this.actions.size) {
       return undefined;
     }
     let actions = [];
     let data = {"type": "key", "actions": actions};
     for (let i=0; i<tickCount; i++) {
       if (this.actions.has(i)) {
         actions.push(this.actions.get(i));
       } else {
         actions.push({"type": "pause"});
       }
     }
     return data;
   },

   keyDown: function(actions, key) {
     let tick = actions.tickIdx;
     if (this.actions.has(tick)) {
       tick = actions.addTick().tickIdx;
     }
     this.actions.set(tick, {type: "keyDown", value: key});
   },

   keyUp: function(actions, key) {
     let tick = actions.tickIdx;
     if (this.actions.has(tick)) {
       tick = actions.addTick().tickIdx;
     }
     this.actions.set(tick, {type: "keyUp", value: key});
   },

   addPause: function(actions, duration) {
     let tick = actions.tickIdx;
     if (this.actions.has(tick)) {
       tick = actions.addTick().tickIdx;
     }
     this.actions.set(tick, {type: "pause", duration: duration});
   },
 };

 function PointerSource(parameters={pointerType: "mouse"}) {
   let pointerType = parameters.pointerType || "mouse";
   if (!["mouse", "pen", "touch"].includes(pointerType)) {
     throw new Error(`Invalid pointerType ${pointerType}`);
   }
   this.type = pointerType;
   this.actions = new Map();
 }

 function setPointerProperties(action, width, height, pressure, tangentialPressure,
                               tiltX, tiltY, twist, altitudeAngle, azimuthAngle) {
   if (width) {
     action.width = width;
   }
   if (height) {
     action.height = height;
   }
   if (pressure) {
     action.pressure = pressure;
   }
   if (tangentialPressure) {
     action.tangentialPressure = tangentialPressure;
   }
   if (tiltX) {
     action.tiltX = tiltX;
   }
   if (tiltY) {
     action.tiltY = tiltY;
   }
   if (twist) {
     action.twist = twist;
   }
   if (altitudeAngle) {
     action.altitudeAngle = altitudeAngle;
   }
   if (azimuthAngle) {
     action.azimuthAngle = azimuthAngle;
   }
   return action;
 }

 PointerSource.prototype = {
   serialize: function(tickCount) {
     if (!this.actions.size) {
       return undefined;
     }
     let actions = [];
     let data = {"type": "pointer", "actions": actions, "parameters": {"pointerType": this.type}};
     for (let i=0; i<tickCount; i++) {
       if (this.actions.has(i)) {
         actions.push(this.actions.get(i));
       } else {
         actions.push({"type": "pause"});
       }
     }
     return data;
   },

   pointerDown: function(actions, button, width, height, pressure, tangentialPressure,
                         tiltX, tiltY, twist, altitudeAngle, azimuthAngle) {
     let tick = actions.tickIdx;
     if (this.actions.has(tick)) {
       tick = actions.addTick().tickIdx;
     }
     let actionProperties = setPointerProperties({type: "pointerDown", button}, width, height,
                                                 pressure, tangentialPressure, tiltX, tiltY,
                                                 twist, altitudeAngle, azimuthAngle);
     this.actions.set(tick, actionProperties);
   },

   pointerUp: function(actions, button) {
     let tick = actions.tickIdx;
     if (this.actions.has(tick)) {
       tick = actions.addTick().tickIdx;
     }
     this.actions.set(tick, {type: "pointerUp", button});
   },

   pointerMove: function(actions, x, y, duration, origin, width, height, pressure,
                         tangentialPressure, tiltX, tiltY, twist, altitudeAngle, azimuthAngle) {
     let tick = actions.tickIdx;
     if (this.actions.has(tick)) {
       tick = actions.addTick().tickIdx;
     }
     let moveAction = {type: "pointerMove", x, y, origin};
     if (duration) {
       moveAction.duration = duration;
     }
     let actionProperties = setPointerProperties(moveAction, width, height, pressure,
                                                 tangentialPressure, tiltX, tiltY, twist,
                                                 altitudeAngle, azimuthAngle);
     this.actions.set(tick, actionProperties);
   },

   addPause: function(actions, duration) {
     let tick = actions.tickIdx;
     if (this.actions.has(tick)) {
       tick = actions.addTick().tickIdx;
     }
     this.actions.set(tick, {type: "pause", duration: duration});
   },
 };

 function WheelSource() {
   this.actions = new Map();
 }

 WheelSource.prototype = {
   serialize: function(tickCount) {
     if (!this.actions.size) {
       return undefined;
     }
     let actions = [];
     let data = {"type": "wheel", "actions": actions};
     for (let i=0; i<tickCount; i++) {
       if (this.actions.has(i)) {
         actions.push(this.actions.get(i));
       } else {
         actions.push({"type": "pause"});
       }
     }
     return data;
   },

   scroll: function(actions, x, y, deltaX, deltaY, duration, origin) {
     let tick = actions.tickIdx;
     if (this.actions.has(tick)) {
       tick = actions.addTick().tickIdx;
     }
     this.actions.set(tick, {type: "scroll", x, y, deltaX, deltaY, origin});
     if (duration) {
       this.actions.get(tick).duration = duration;
     }
   },

   addPause: function(actions, duration) {
     let tick = actions.tickIdx;
     if (this.actions.has(tick)) {
       tick = actions.addTick().tickIdx;
     }
     this.actions.set(tick, {type: "pause", duration: duration});
   },
 };

 test_driver.Actions = Actions;
})();