import FIREFOX_52_6_0esr_RELEASE from mozilla-esr52 hg repo

testing/marionette/evaluate.js

@@ -0,0 +1,494 @@
+/* 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 {classes: Cc, interfaces: Ci, utils: Cu} = Components;
+
+Cu.import("resource://gre/modules/Log.jsm");
+Cu.import("resource://gre/modules/NetUtil.jsm");
+Cu.import("resource://gre/modules/Timer.jsm");
+Cu.import("resource://gre/modules/XPCOMUtils.jsm");
+
+Cu.import("chrome://marionette/content/error.js");
+
+const logger = Log.repository.getLogger("Marionette");
+
+this.EXPORTED_SYMBOLS = ["evaluate", "sandbox", "Sandboxes"];
+
+const ARGUMENTS = "__webDriverArguments";
+const CALLBACK = "__webDriverCallback";
+const COMPLETE = "__webDriverComplete";
+const DEFAULT_TIMEOUT = 10000; // ms
+const FINISH = "finish";
+const MARIONETTE_SCRIPT_FINISHED = "marionetteScriptFinished";
+const ELEMENT_KEY = "element";
+const W3C_ELEMENT_KEY = "element-6066-11e4-a52e-4f735466cecf";
+
+this.evaluate = {};
+
+/**
+ * Evaluate a script in given sandbox.
+ *
+ * If the option {@code directInject} is not specified, the script will
+ * be executed as a function with the {@code args} argument applied.
+ *
+ * The arguments provided by the {@code args} argument are exposed through
+ * the {@code arguments} object available in the script context, and if
+ * the script is executed asynchronously with the {@code async}
+ * option, an additional last argument that is synonymous to the
+ * {@code marionetteScriptFinished} global is appended, and can be
+ * accessed through {@code arguments[arguments.length - 1]}.
+ *
+ * The {@code timeout} option specifies the duration for how long the
+ * script should be allowed to run before it is interrupted and aborted.
+ * An interrupted script will cause a ScriptTimeoutError to occur.
+ *
+ * The {@code async} option indicates that the script will not return
+ * until the {@code marionetteScriptFinished} global callback is invoked,
+ * which is analogous to the last argument of the {@code arguments}
+ * object.
+ *
+ * The option {@code directInject} causes the script to be evaluated
+ * without being wrapped in a function and the provided arguments will
+ * be disregarded.  This will cause such things as root scope return
+ * statements to throw errors because they are not used inside a function.
+ *
+ * The {@code filename} option is used in error messages to provide
+ * information on the origin script file in the local end.
+ *
+ * The {@code line} option is used in error messages, along with
+ * {@code filename}, to provide the line number in the origin script
+ * file on the local end.
+ *
+ * @param {nsISandbox) sb
+ *     The sandbox the script will be evaluted in.
+ * @param {string} script
+ *     The script to evaluate.
+ * @param {Array.<?>=} args
+ *     A sequence of arguments to call the script with.
+ * @param {Object.<string, ?>=} opts
+ *     Dictionary of options:
+ *
+ *       async (boolean)
+ *         Indicates if the script should return immediately or wait
+ *         for the callback be invoked before returning.
+ *       debug (boolean)
+ *         Attaches an {@code onerror} event listener.
+ *       directInject (boolean)
+ *         Evaluates the script without wrapping it in a function.
+ *       filename (string)
+ *         File location of the program in the client.
+ *       line (number)
+ *         Line number of the program in the client.
+ *       sandboxName (string)
+ *         Name of the sandbox.  Elevated system privileges, equivalent
+ *         to chrome space, will be given if it is "system".
+ *       timeout (boolean)
+ *         Duration in milliseconds before interrupting the script.
+ *
+ * @return {Promise}
+ *     A promise that when resolved will give you the return value from
+ *     the script.  Note that the return value requires serialisation before
+ *     it can be sent to the client.
+ *
+ * @throws JavaScriptError
+ *   If an Error was thrown whilst evaluating the script.
+ * @throws ScriptTimeoutError
+ *   If the script was interrupted due to script timeout.
+ */
+evaluate.sandbox = function (sb, script, args = [], opts = {}) {
+  let scriptTimeoutID, timeoutHandler, unloadHandler;
+
+  let promise = new Promise((resolve, reject) => {
+    let src = "";
+    sb[COMPLETE] = resolve;
+    timeoutHandler = () => reject(new ScriptTimeoutError("Timed out"));
+    unloadHandler = () => reject(
+        new JavaScriptError("Document was unloaded during execution"));
+
+    // wrap in function
+    if (!opts.directInject) {
+      if (opts.async) {
+        sb[CALLBACK] = sb[COMPLETE];
+      }
+      sb[ARGUMENTS] = sandbox.cloneInto(args, sb);
+
+      // callback function made private
+      // so that introspection is possible
+      // on the arguments object
+      if (opts.async) {
+        sb[CALLBACK] = sb[COMPLETE];
+        src += `${ARGUMENTS}.push(rv => ${CALLBACK}(rv));`;
+      }
+
+      src += `(function() { ${script} }).apply(null, ${ARGUMENTS})`;
+
+      // marionetteScriptFinished is not WebDriver conformant,
+      // hence it is only exposed to immutable sandboxes
+      if (opts.sandboxName) {
+        sb[MARIONETTE_SCRIPT_FINISHED] = sb[CALLBACK];
+      }
+    }
+
+    // onerror is not hooked on by default because of the inability to
+    // differentiate content errors from chrome errors.
+    //
+    // see bug 1128760 for more details
+    if (opts.debug) {
+      sb.window.onerror = (msg, url, line) => {
+        let err = new JavaScriptError(`${msg} at ${url}:${line}`);
+        reject(err);
+      };
+    }
+
+    // timeout and unload handlers
+    scriptTimeoutID = setTimeout(timeoutHandler, opts.timeout || DEFAULT_TIMEOUT);
+    sb.window.onunload = sandbox.cloneInto(unloadHandler, sb);
+
+    let res;
+    try {
+      res = Cu.evalInSandbox(src, sb, "1.8", opts.filename || "dummy file", 0);
+    } catch (e) {
+      let err = new JavaScriptError(
+          e,
+          "execute_script",
+          opts.filename,
+          opts.line,
+          script);
+      reject(err);
+    }
+
+    if (!opts.async) {
+      resolve(res);
+    }
+  });
+
+  return promise.then(res => {
+    clearTimeout(scriptTimeoutID);
+    sb.window.removeEventListener("unload", unloadHandler);
+    return res;
+  });
+};
+
+this.sandbox = {};
+
+/**
+ * Provides a safe way to take an object defined in a privileged scope and
+ * create a structured clone of it in a less-privileged scope.  It returns
+ * a reference to the clone.
+ *
+ * Unlike for |Components.utils.cloneInto|, |obj| may contain functions
+ * and DOM elemnets.
+ */
+sandbox.cloneInto = function (obj, sb) {
+  return Cu.cloneInto(obj, sb, {cloneFunctions: true, wrapReflectors: true});
+};
+
+/**
+ * Augment given sandbox by an adapter that has an {@code exports}
+ * map property, or a normal map, of function names and function
+ * references.
+ *
+ * @param {Sandbox} sb
+ *     The sandbox to augment.
+ * @param {Object} adapter
+ *     Object that holds an {@code exports} property, or a map, of
+ *     function names and function references.
+ *
+ * @return {Sandbox}
+ *     The augmented sandbox.
+ */
+sandbox.augment = function (sb, adapter) {
+  function* entries(obj) {
+     for (let key of Object.keys(obj)) {
+       yield [key, obj[key]];
+     }
+  }
+
+  let funcs = adapter.exports || entries(adapter);
+  for (let [name, func] of funcs) {
+    sb[name] = func;
+  }
+
+  return sb;
+};
+
+/**
+ * Creates a sandbox.
+ *
+ * @param {Window} window
+ *     The DOM Window object.
+ * @param {nsIPrincipal=} principal
+ *     An optional, custom principal to prefer over the Window.  Useful if
+ *     you need elevated security permissions.
+ *
+ * @return {Sandbox}
+ *     The created sandbox.
+ */
+sandbox.create = function (window, principal = null, opts = {}) {
+  let p = principal || window;
+  opts = Object.assign({
+    sameZoneAs: window,
+    sandboxPrototype: window,
+    wantComponents: true,
+    wantXrays: true,
+  }, opts);
+  return new Cu.Sandbox(p, opts);
+};
+
+/**
+ * Creates a mutable sandbox, where changes to the global scope
+ * will have lasting side-effects.
+ *
+ * @param {Window} window
+ *     The DOM Window object.
+ *
+ * @return {Sandbox}
+ *     The created sandbox.
+ */
+sandbox.createMutable = function (window) {
+  let opts = {
+    wantComponents: false,
+    wantXrays: false,
+  };
+  return sandbox.create(window, null, opts);
+};
+
+sandbox.createSystemPrincipal = function (window) {
+  let principal = Cc["@mozilla.org/systemprincipal;1"]
+      .createInstance(Ci.nsIPrincipal);
+  return sandbox.create(window, principal);
+};
+
+sandbox.createSimpleTest = function (window, harness) {
+  let sb = sandbox.create(window);
+  sb = sandbox.augment(sb, harness);
+  sb[FINISH] = () => sb[COMPLETE](harness.generate_results());
+  return sb;
+};
+
+/**
+ * Sandbox storage.  When the user requests a sandbox by a specific name,
+ * if one exists in the storage this will be used as long as its window
+ * reference is still valid.
+ */
+this.Sandboxes = class {
+  /**
+   * @param {function(): Window} windowFn
+   *     A function that returns the references to the current Window
+   *     object.
+   */
+  constructor(windowFn) {
+    this.windowFn_ = windowFn;
+    this.boxes_ = new Map();
+  }
+
+  get window_() {
+    return this.windowFn_();
+  }
+
+  /**
+   * Factory function for getting a sandbox by name, or failing that,
+   * creating a new one.
+   *
+   * If the sandbox' window does not match the provided window, a new one
+   * will be created.
+   *
+   * @param {string} name
+   *     The name of the sandbox to get or create.
+   * @param {boolean} fresh
+   *     Remove old sandbox by name first, if it exists.
+   *
+   * @return {Sandbox}
+   *     A used or fresh sandbox.
+   */
+  get(name = "default", fresh = false) {
+    let sb = this.boxes_.get(name);
+    if (sb) {
+      if (fresh || sb.window != this.window_) {
+        this.boxes_.delete(name);
+        return this.get(name, false);
+      }
+    } else {
+      if (name == "system") {
+        sb = sandbox.createSystemPrincipal(this.window_);
+      } else {
+        sb = sandbox.create(this.window_);
+      }
+      this.boxes_.set(name, sb);
+    }
+    return sb;
+  }
+
+  /**
+   * Clears cache of sandboxes.
+   */
+  clear() {
+    this.boxes_.clear();
+  }
+};
+
+/**
+ * Stores scripts imported from the local end through the
+ * {@code GeckoDriver#importScript} command.
+ *
+ * Imported scripts are prepended to the script that is evaluated
+ * on each call to {@code GeckoDriver#executeScript},
+ * {@code GeckoDriver#executeAsyncScript}, and
+ * {@code GeckoDriver#executeJSScript}.
+ *
+ * Usage:
+ *
+ *     let importedScripts = new evaluate.ScriptStorage();
+ *     importedScripts.add(firstScript);
+ *     importedScripts.add(secondScript);
+ *
+ *     let scriptToEval = importedScripts.concat(script);
+ *     // firstScript and secondScript are prepended to script
+ *
+ */
+evaluate.ScriptStorage = class extends Set {
+
+  /**
+   * Produce a string of all stored scripts.
+   *
+   * The stored scripts are concatenated into a string, with optional
+   * additional scripts then appended.
+   *
+   * @param {...string} addional
+   *     Optional scripts to include.
+   *
+   * @return {string}
+   *     Concatenated string consisting of stored scripts and additional
+   *     scripts, in that order.
+   */
+  concat(...additional) {
+    let rv = "";
+    for (let s of this) {
+      rv = s + rv;
+    }
+    for (let s of additional) {
+      rv = rv + s;
+    }
+    return rv;
+  }
+
+  toJson() {
+    return Array.from(this);
+  }
+
+};
+
+/**
+ * Service that enables the script storage service to be queried from
+ * content space.
+ *
+ * The storage can back multiple |ScriptStorage|, each typically belonging
+ * to a |Context|.  Since imported scripts' scope are global and not
+ * scoped to the current browsing context, all imported scripts are stored
+ * in chrome space and fetched by content space as needed.
+ *
+ * Usage in chrome space:
+ *
+ *     let service = new evaluate.ScriptStorageService(
+ *         [Context.CHROME, Context.CONTENT]);
+ *     let storage = service.for(Context.CHROME);
+ *     let scriptToEval = storage.concat(script);
+ *
+ */
+evaluate.ScriptStorageService = class extends Map {
+
+  /**
+   * Create the service.
+   *
+   * An optional array of names for script storages to initially create
+   * can be provided.
+   *
+   * @param {Array.<string>=} initialStorages
+   *     List of names of the script storages to create initially.
+   */
+  constructor(initialStorages = []) {
+    super(initialStorages.map(name => [name, new evaluate.ScriptStorage()]));
+  }
+
+  /**
+   * Retrieve the scripts associated with the given context.
+   *
+   * @param {Context} context
+   *     Context to retrieve the scripts from.
+   *
+   * @return {ScriptStorage}
+   *     Scrips associated with given |context|.
+   */
+  for(context) {
+    return this.get(context);
+  }
+
+  processMessage(msg) {
+    switch (msg.name) {
+      case "Marionette:getImportedScripts":
+        let storage = this.for.apply(this, msg.json);
+        return storage.toJson();
+
+      default:
+        throw new TypeError("Unknown message: " + msg.name);
+    }
+  }
+
+  // TODO(ato): The idea of services in chrome space
+  // can be generalised at some later time (see cookies.js:38).
+  receiveMessage(msg) {
+    try {
+      return this.processMessage(msg);
+    } catch (e) {
+      logger.error(e);
+    }
+  }
+
+};
+
+evaluate.ScriptStorageService.prototype.QueryInterface =
+    XPCOMUtils.generateQI([
+      Ci.nsIMessageListener,
+      Ci.nsISupportsWeakReference,
+    ]);
+
+/**
+ * Bridges the script storage in chrome space, to make it possible to
+ * retrieve a {@code ScriptStorage} associated with a given
+ * {@code Context} from content space.
+ *
+ * Usage in content space:
+ *
+ *     let client = new evaluate.ScriptStorageServiceClient(chromeProxy);
+ *     let storage = client.for(Context.CONTENT);
+ *     let scriptToEval = storage.concat(script);
+ *
+ */
+evaluate.ScriptStorageServiceClient = class {
+
+  /**
+   * @param {proxy.SyncChromeSender} chromeProxy
+   *     Proxy for communicating with chrome space.
+   */
+  constructor(chromeProxy) {
+    this.chrome = chromeProxy;
+  }
+
+  /**
+   * Retrieve scripts associated with the given context.
+   *
+   * @param {Context} context
+   *     Context to retrieve scripts from.
+   *
+   * @return {ScriptStorage}
+   *     Scripts associated with given |context|.
+   */
+  for(context) {
+    let scripts = this.chrome.getImportedScripts(context)[0];
+    return new evaluate.ScriptStorage(scripts);
+  }
+
+};