Update webdriver.atoms.inject.locators.* to support finding elements

in another window or frame. The search operation can no longer be
piped through bot.inject.executeScript since it violates the contract
of only referencing symbols defined in the context of the target
frame.

Author: jleyba

javascript/atoms/inject.js

@@ -216,7 +216,8 @@ bot.inject.recompileFunction_ = function(fn, theWindow) {
  * @param {!(Function|string)} fn Either the function to execute, or a string
  *     defining the body of an anonymous function that should be executed. This
  *     function should only contain references to symbols defined in the context
- *     of the current window.
+ *     of the target window ({@code opt_window}). Any references to symbols
+ *     defined in this context will likely generate a ReferenceError.
  * @param {Array.<*>} args An array of wrapped script arguments, as defined by
  *     the WebDriver wire protocol.
  * @param {boolean=} opt_stringify Whether the result should be returned as a
@@ -261,8 +262,11 @@ bot.inject.executeScript = function(fn, args, opt_stringify, opt_window) {
  * from an external source. It handles wrapping and unwrapping of input/output
  * values.
  *
- * @param {(function()|string)} fn Either the function to execute, or a string
- *     defining the body of an anonymous function that should be executed.
+ * @param {(!Function|string)} fn Either the function to execute, or a string
+ *     defining the body of an anonymous function that should be executed. This
+ *     function should only contain references to symbols defined in the context
+ *     of the target window ({@code opt_window}). Any references to symbols
+ *     defined in this context will likely generate a ReferenceError.
  * @param {Array.<*>} args An array of wrapped script arguments, as defined by
  *     the WebDriver wire protocol.
  * @param {number} timeout The amount of time, in milliseconds, the script

javascript/webdriver/atoms/inject/execute_script.js

@@ -29,14 +29,14 @@ goog.require('bot.inject.cache');
  *
  * @param {!(string|Function)} fn The function to execute.
  * @param {Array.<*>} args Array of arguments to pass to fn.
- * @param {{bot.inject.WINDOW_KEY:string}=} opt_window The serialized window
- *     object to be read from the cache.
+ * @param {{WINDOW: string}=} opt_window The serialized window object to be
+ *     read from the cache.
  * @return {string} The response object, serialized and returned in string
  *     format.
  */
 webdriver.atoms.inject.executeScript = function(fn, args, opt_window) {
   return /**@type {string}*/(bot.inject.executeScript(fn, args, true,
-      webdriver.atoms.inject.getWindow_(opt_window)));
+      webdriver.atoms.inject.getWindow(opt_window)));
 };
 
 
@@ -48,26 +48,29 @@ webdriver.atoms.inject.executeScript = function(fn, args, opt_window) {
  * @param {function(string)|function(!bot.response.ResponseObject)} onDone
  *     The function to call when the given {@code fn} invokes its callback,
  *     or when an exception or timeout occurs. This will always be called.
- * @param {{bot.inject.WINDOW_KEY:string}=} opt_window The serialized window
+ * @param {{WINDOW: string}=} opt_window The serialized window
  *     object to be read from the cache.
  */
 webdriver.atoms.inject.executeAsyncScript =
     function(fn, args, timeout, onDone, opt_window) {
   bot.inject.executeAsyncScript(
       fn, args, timeout, onDone, true,
-      webdriver.atoms.inject.getWindow_(opt_window));
+      webdriver.atoms.inject.getWindow(opt_window));
 };
 
 
 /**
- * Get the window to use.
+ * Decodes a serialized {WINDOW: string} object using the current document's
+ * cache.
  *
- * @param {{bot.inject.WINDOW_KEY:string}=} opt_window The serialized window
- *     object to be read from the cache.
+ * @param {{WINDOW: string}=} opt_window The serialized window object to be
+ *     read from the cache. If undefined, this function will trivially return
+ *     the current window.
  * @return {!Window} A reference to a window.
- * @private
+ * @throws {bot.Error} If the serialized window cannot be found in the current
+ *     document's cache.
  */
-webdriver.atoms.inject.getWindow_ = function(opt_window) {
+webdriver.atoms.inject.getWindow = function(opt_window) {
   var win;
   if (opt_window) {
     win = bot.inject.cache.getElement(opt_window[bot.inject.WINDOW_KEY]);

javascript/webdriver/atoms/inject/find_element.js

@@ -20,41 +20,90 @@
 goog.provide('webdriver.atoms.inject.locators');
 
 goog.require('bot.locators');
+goog.require('bot.inject');
 goog.require('webdriver.atoms.inject');
 
+
 /**
  * Finds an element by using the given lookup strategy.
  * @param {string} strategy The strategy to use to locate the element.
  * @param {string} using The locator to use.
- * @param {(Document|Element)=} opt_root The document or element to perform
- *     the search under. If not specified, will use {@code document}
- *     as the root.
- * @return {string} The result wrapped
- *     in a JSON string as defined by the WebDriver wire protocol.
+ * @param {?{ELEMENT: string}=} opt_root The WebElement reference for the
+ *     element to perform the search under. If not specified, will use
+ *     {@code document} for the target page.
+ * @param {{WINDOW:string}=} opt_window The serialized window object for the
+ *     page to find the element in. The referenced window must exist in the
+ *     page executing this script's cache.
+ * @return {string} A JSON serialized {@link bot.response.ResponseObject}.
  */
-webdriver.atoms.inject.locators.findElement =
-    function(strategy, using, opt_root) {
-  var locator = {};
-  locator[strategy] = using;
-  return webdriver.atoms.inject.executeScript(bot.locators.findElement,
-      [locator, opt_root]);
+webdriver.atoms.inject.locators.findElement = function(
+    strategy, using, opt_root, opt_window) {
+  return webdriver.atoms.inject.locators.performSearch_(
+      strategy, using, bot.locators.findElement, opt_root, opt_window);
 };
 
 
 /**
  * Finds all elements by using the given lookup strategy.
  * @param {string} strategy The strategy to use to locate the element.
  * @param {string} using The locator to use.
- * @param {(Document|Element)=} opt_root The document or element to perform
- *     the search under. If not specified, will use {@code document}
- *     as the root.
- * @return {string} The result wrapped
- *     in a JSON string as defined by the WebDriver wire protocol.
+ * @param {?{ELEMENT: string}=} opt_root The WebElement reference for the
+ *     element to perform the search under. If not specified, will use
+ *     {@code document} for the target page.
+ * @param {{WINDOW:string}=} opt_window The serialized window object for the
+ *     page to find the element in. The referenced window must exist in the
+ *     page executing this script's cache.
+ * @return {string} A JSON serialized {@link bot.response.ResponseObject}.
  */
-webdriver.atoms.inject.locators.findElements =
-    function(strategy, using, opt_root) {
-  var locator = {};
-  locator[strategy] = using;
-  return webdriver.atoms.inject.executeScript(bot.locators.findElements,
-      [locator, opt_root]);
+webdriver.atoms.inject.locators.findElements = function(
+    strategy, using, opt_root, opt_window) {
+  return webdriver.atoms.inject.locators.performSearch_(
+      strategy, using, bot.locators.findElements, opt_root, opt_window);
+};
+
+
+/**
+ * Performs a search for one or more elements.
+ * @param {string} strategy The strategy to use to locate the element.
+ * @param {string} target The locator to use.
+ * @param {(function(!Object, (Document|Element)=): Element|
+ *          function(!Object, (Document|Element)=): !goog.array.ArrayLike)}
+ *     searchFn The search function to invoke.
+ * @param {?{ELEMENT: string}=} opt_root The WebElement reference for the
+ *     element to perform the search under. If not specified, will use
+ *     {@code document} for the target page.
+ * @param {{WINDOW:string}=} opt_window The serialized window object for the
+ *     page to find the element in. The referenced window must exist in the
+ *     page executing this script's cache.
+ * @return {string} A JSON serialized {@link bot.response.ResponseObject}.
+ * @private
+ */
+webdriver.atoms.inject.locators.performSearch_ = function(
+    strategy, target, searchFn, opt_root, opt_window) {
+    var locator = {};
+  locator[strategy] = target;
+
+  var response;
+  try {
+    // Step 1: find the window we are locating the element in.
+    var targetWindow = webdriver.atoms.inject.getWindow(opt_window);
+
+    // Step 2: decode the root of our search.
+    var root;
+    if (opt_root) {
+      root = /** @type {!Element} */ (bot.inject.cache.getElement(
+          opt_root[bot.inject.ELEMENT_KEY], targetWindow.document));
+    } else {
+      root = targetWindow.document;
+    }
+
+    // Step 3: perform the search.
+    var found = searchFn(locator, root);
+
+    // Step 4: encode our response.
+    response = bot.inject.wrapResponse(found);
+  } catch (ex) {
+    response = bot.inject.wrapError(ex);
+  }
+  return goog.json.serialize(response);
 };