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 for manipulating the DOM.
20
 */
21

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

24
goog.require('bot.action');
25
goog.require('bot.inject');
26
goog.require('goog.json');
27
goog.require('webdriver.atoms.element');
28
goog.require('webdriver.atoms.inject');
29
goog.require('webdriver.atoms.inputs');
30

31

32
/**
33
 * Sends key events to simulating typing on an element.
34
 *
35
 * @param {bot.inject.JsonElement} element The element to submit.
36
 * @param {!Array.<string>} keys The keys to type.
37
 * @param {bot.inject.JsonWindow=} opt_window The optional window
38
 *     containing the element.
39
 * @return {string} A stringified {@link bot.response.ResponseObject}.
40
 */
41
webdriver.atoms.inject.action.type = function(element, keys, opt_window) {
42
  return webdriver.atoms.inject.action.executeActionFunction_(
43
      webdriver.atoms.element.type, [element, keys], opt_window);
44
};
45

46

47
/**
48
 * Submits the form containing the given element.
49
 *
50
 * @param {bot.inject.JsonElement} element The element to submit.
51
 * @param {bot.inject.JsonWindow=} opt_window The optional window
52
 *     containing the element.
53
 * @return {string} A stringified {@link bot.response.ResponseObject}.
54
 * @deprecated Click on a submit button or type ENTER in a text box instead.
55
 */
56
webdriver.atoms.inject.action.submit = function(element, opt_window) {
57
  return webdriver.atoms.inject.action.executeActionFunction_(bot.action.submit,
58
      [element], opt_window);
59
};
60

61

62
/**
63
 * Clear an element.
64
 *
65
 * @param {bot.inject.JsonElement} element The element to clear.
66
 * @param {bot.inject.JsonWindow=} opt_window The optional window
67
 *     containing the element.
68
 * @return {string} A stringified {@link bot.response.ResponseObject}.
69
 * @see bot.action.clear
70
 */
71
webdriver.atoms.inject.action.clear = function(element, opt_window) {
72
  return webdriver.atoms.inject.action.executeActionFunction_(bot.action.clear,
73
      [element], opt_window);
74
};
75

76

77
/**
78
 * Click an element.
79
 *
80
 * @param {bot.inject.JsonElement} element The element to click.
81
 * @param {bot.inject.JsonWindow=} opt_window The optional window
82
 *     containing the element.
83
 * @return {string} A stringified {@link bot.response.ResponseObject}.
84
 * @see bot.action.click
85
 */
86
webdriver.atoms.inject.action.click = function (element, opt_window) {
87
  return webdriver.atoms.inject.action.executeActionFunction_(bot.action.click,
88
      [element], opt_window);
89
};
90

91

92
/**
93
 * JSON representation of a {@link bot.Mouse.State} object.
94
 * @typedef {{buttonPressed: ?bot.Mouse.Button,
95
 *            elementPressed: ?bot.inject.JsonElement,
96
 *            clientXY: {x: number, y: number},
97
 *            nextClickIsDoubleClick: boolean,
98
 *            hasEverInteracted: boolean,
99
 *            element: ?bot.inject.JsonElement}}
100
 */
101
webdriver.atoms.inject.action.JsonMouseState;
102

103

104
/**
105
 * Clicks a mouse button.
106
 *
107
 * @param {bot.Mouse.Button} button The button to press.
108
 * @param {webdriver.atoms.inject.action.JsonMouseState=} opt_mouseState The
109
 *     current state of the mouse.
110
 * @param {bot.inject.JsonWindow=} opt_window The window context for
111
 *     the execution of the function.
112
 * @return {string} A stringified {@link bot.response.ResponseObject}. The
113
 *     mouse's new state, as a
114
 *     {@link webdriver.atoms.inject.action.JsonMouseState} will be included
115
 *     as the response value.
116
 */
117
webdriver.atoms.inject.action.mouseClick = function(
118
    button, opt_mouseState, opt_window) {
119
  return webdriver.atoms.inject.action.executeActionFunction_(
120
      webdriver.atoms.inputs.mouseClick,
121
      [button, opt_mouseState], opt_window);
122
};
123

124

125
/**
126
 * Types a sequence of key strokes on the active element.
127
 * @param {!Array.<string>} keys The keys to type.
128
 * @param {bot.Keyboard.State=} opt_keyboardState The keyboard's state.
129
 * @param {bot.inject.JsonWindow=} opt_window The window context for
130
 *     the execution of the function.
131
 * @return {string} A stringified {@link bot.response.ResponseObject}. The
132
 *     keyboard's new state, as a {@link bot.Keyboard.State} will be included
133
 *     as the response value.
134
 */
135
webdriver.atoms.inject.action.sendKeysToActiveElement = function(
136
    keys, opt_keyboardState, opt_window) {
137
  var persistModifiers = true;
138
  return webdriver.atoms.inject.action.executeActionFunction_(
139
      webdriver.atoms.inputs.sendKeys,
140
      [null, keys, opt_keyboardState, persistModifiers], opt_window);
141
};
142

143
/**
144
  * Moves the mouse to a specific element and/or coordinate location.
145
  *
146
  * @param {?bot.inject.JsonElement} element The element to move the mouse
147
  *     relative to, or `null` to use the mouse's current position.
148
  * @param {?number} xOffset A horizontal offset, relative to the left edge of
149
  *     the given element, or the mouse's current position if no element is
150
  *     specified.
151
  * @param {?number} yOffset A vertical offset, relative to the top edge of
152
  *     the given element, or the mouse's current position if no element
153
  *     is specified.
154
  * @param {webdriver.atoms.inject.action.JsonMouseState=} opt_mouseState The
155
  *     current state of the mouse.
156
  * @param {bot.inject.JsonWindow=} opt_window The window context for
157
  *     the execution of the function.
158
  * @return {string} A stringified {@link bot.response.ResponseObject}. The
159
  *     mouse's new state, as a
160
  *     {@link webdriver.atoms.inject.action.JsonMouseState} will be included
161
  *     as the response value.
162
  */
163
webdriver.atoms.inject.action.mouseMove = function(
164
    element, xOffset, yOffset, opt_mouseState, opt_window) {
165
  return webdriver.atoms.inject.action.executeActionFunction_(
166
      webdriver.atoms.inputs.mouseMove,
167
      [element, xOffset, yOffset, opt_mouseState], opt_window);
168
};
169

170

171
/**
172
 * Presses the primary mouse button at the current location.
173
 *
174
 * @param {webdriver.atoms.inject.action.JsonMouseState=} opt_mouseState The
175
 *     current state of the mouse.
176
 * @param {bot.inject.JsonWindow=} opt_window The window context for
177
 *     the execution of the function.
178
 * @return {string} A stringified {@link bot.response.ResponseObject}. The
179
 *     mouse's new state, as a
180
 *     {@link webdriver.atoms.inject.action.JsonMouseState} will be included
181
 *     as the response value.
182
 */
183
webdriver.atoms.inject.action.mouseButtonDown = function(opt_mouseState, opt_window) {
184
  return webdriver.atoms.inject.action.executeActionFunction_(
185
      webdriver.atoms.inputs.mouseButtonDown,
186
      [opt_mouseState], opt_window);
187
};
188

189

190
/**
191
 * Releases the primary mouse button at the current location.
192
 *
193
 * @param {webdriver.atoms.inject.action.JsonMouseState=} opt_mouseState The
194
 *     current state of the mouse.
195
 * @param {bot.inject.JsonWindow=} opt_window The window context for
196
 *     the execution of the function.
197
 * @return {string} A stringified {@link bot.response.ResponseObject}. The
198
 *     mouse's new state, as a
199
 *     {@link webdriver.atoms.inject.action.JsonMouseState} will be included
200
 *     as the response value.
201
 */
202
webdriver.atoms.inject.action.mouseButtonUp = function(opt_mouseState, opt_window) {
203
  return webdriver.atoms.inject.action.executeActionFunction_(
204
      webdriver.atoms.inputs.mouseButtonUp,
205
      [opt_mouseState], opt_window);
206
};
207

208
/**
209
* Double-clicks the primary mouse button.
210
*
211
* @param {webdriver.atoms.inject.action.JsonMouseState=} opt_mouseState The
212
*     current state of the mouse.
213
* @param {bot.inject.JsonWindow=} opt_window The window context for
214
*     the execution of the function.
215
* @return {string} A stringified {@link bot.response.ResponseObject}. The
216
*     mouse's new state, as a
217
*     {@link webdriver.atoms.inject.action.JsonMouseState} will be included
218
*     as the response value.
219
*/
220
webdriver.atoms.inject.action.doubleClick = function (
221
    opt_mouseState, opt_window) {
222
    return webdriver.atoms.inject.action.executeActionFunction_(
223
      webdriver.atoms.inputs.doubleClick,
224
      [opt_mouseState], opt_window);
225
};
226

227

228
/**
229
 * @param {!Function} fn The function to call.
230
 * @param {!Array.<*>} args An array of function arguments for the function.
231
 * @param {bot.inject.JsonWindow=} opt_window The window context for
232
 *     the execution of the function.
233
 * @return {string} The serialized JSON wire protocol result of the function.
234
 * @private
235
 */
236
webdriver.atoms.inject.action.executeActionFunction_ = function (
237
    fn, args, opt_window) {
238
  var response;
239
  try {
240
    var targetWindow = webdriver.atoms.inject.getWindow(opt_window);
241
    var unwrappedArgs = /** @type {Array} */(bot.inject.unwrapValue(
242
        args, targetWindow.document));
243
    var functionResult = fn.apply(null, unwrappedArgs);
244
    response = bot.inject.wrapResponse(functionResult);
245
  } catch (ex) {
246
    response = bot.inject.wrapError(ex);
247
  }
248
  return goog.json.serialize(response);
249
};
250

251