1
// Licensed to the Software Freedom Conservancy (SFC) under one
2
// or more contributor license agreements.  See the NOTICE file
3
// distributed with this work for additional information
4
// regarding copyright ownership.  The SFC licenses this file
5
// to you under the Apache License, Version 2.0 (the
6
// "License"); you may not use this file except in compliance
7
// with the License.  You may obtain a copy of the License at
8
//
9
//   http://www.apache.org/licenses/LICENSE-2.0
10
//
11
// Unless required by applicable law or agreed to in writing,
12
// software distributed under the License is distributed on an
13
// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
14
// KIND, either express or implied.  See the License for the
15
// specific language governing permissions and limitations
16
// under the License.
17

18
/**
19
 * @fileoverview Ready to inject atoms to find elements in the page.
20
 */
21

22
goog.provide('webdriver.atoms.inject.locators');
23

24
goog.require('bot.inject');
25
goog.require('bot.inject.cache');
26
goog.require('bot.locators');
27
goog.require('goog.json');
28
goog.require('webdriver.atoms.inject');
29

30

31
/**
32
 * Finds an element by using the given lookup strategy.
33
 * @param {string} strategy The strategy to use to locate the element.
34
 * @param {string} using The locator to use.
35
 * @param {?{ELEMENT: string}=} opt_root The WebElement reference for the
36
 *     element to perform the search under. If not specified, will use
37
 *     `document` for the target page.
38
 * @param {{WINDOW: string}=} opt_window The serialized window object for the
39
 *     page to find the element in. The referenced window must exist in the
40
 *     page executing this script's cache.
41
 * @return {string} A JSON serialized {@link bot.response.ResponseObject}.
42
 */
43
webdriver.atoms.inject.locators.findElement = function(
44
    strategy, using, opt_root, opt_window) {
45
  return webdriver.atoms.inject.locators.performSearch_(
46
      strategy, using, bot.locators.findElement, opt_root, opt_window);
47
};
48

49

50
/**
51
 * Finds all elements by using the given lookup strategy.
52
 * @param {string} strategy The strategy to use to locate the element.
53
 * @param {string} using The locator to use.
54
 * @param {?{ELEMENT: string}=} opt_root The WebElement reference for the
55
 *     element to perform the search under. If not specified, will use
56
 *     `document` for the target page.
57
 * @param {{WINDOW: string}=} opt_window The serialized window object for the
58
 *     page to find the element in. The referenced window must exist in the
59
 *     page executing this script's cache.
60
 * @return {string} A JSON serialized {@link bot.response.ResponseObject}.
61
 */
62
webdriver.atoms.inject.locators.findElements = function(
63
    strategy, using, opt_root, opt_window) {
64
  return webdriver.atoms.inject.locators.performSearch_(
65
      strategy, using, bot.locators.findElements, opt_root, opt_window);
66
};
67

68

69
/**
70
 * Performs a search for one or more elements.
71
 * @param {string} strategy The strategy to use to locate the element.
72
 * @param {string} target The locator to use.
73
 * @param {(function(!Object, (Document|Element)=): Element|
74
 *          function(!Object, (Document|Element)=): !IArrayLike)}
75
 *     searchFn The search function to invoke.
76
 * @param {?{ELEMENT: string}=} opt_root The WebElement reference for the
77
 *     element to perform the search under. If not specified, will use
78
 *     `document` for the target page.
79
 * @param {{WINDOW: string}=} opt_window The serialized window object for the
80
 *     page to find the element in. The referenced window must exist in the
81
 *     page executing this script's cache.
82
 * @return {string} A JSON serialized {@link bot.response.ResponseObject}.
83
 * @private
84
 */
85
webdriver.atoms.inject.locators.performSearch_ = function(
86
    strategy, target, searchFn, opt_root, opt_window) {
87
  var locator = {};
88
  locator[strategy] = target;
89

90
  var response;
91
  try {
92
    // Step 1: find the window we are locating the element in.
93
    var targetWindow = webdriver.atoms.inject.getWindow(opt_window);
94

95
    // Step 2: decode the root of our search.
96
    var root;
97
    if (opt_root) {
98
      root = /** @type {!Element} */ (bot.inject.cache.getElement(
99
          opt_root[bot.inject.ELEMENT_KEY], targetWindow.document));
100
    } else {
101
      root = targetWindow.document;
102
    }
103

104
    // Step 3: perform the search.
105
    var found = searchFn(locator, root);
106

107
    // Step 4: encode our response.
108
    response = bot.inject.wrapResponse(found);
109
  } catch (ex) {
110
    response = bot.inject.wrapError(ex);
111
  }
112
  return goog.json.serialize(response);
113
};
114

115