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 Contains several classes for handling commands.
20
 */
21

22
goog.provide('webdriver.Command');
23
goog.provide('webdriver.CommandExecutor');
24
goog.provide('webdriver.CommandName');
25

26

27

28
/**
29
 * Describes a command to be executed by the WebDriverJS framework.
30
 * @param {!webdriver.CommandName} name The name of this command.
31
 * @constructor
32
 */
33
webdriver.Command = function(name) {
34

35
  /**
36
   * The name of this command.
37
   * @private {!webdriver.CommandName}
38
   */
39
  this.name_ = name;
40

41
  /**
42
   * The parameters to this command.
43
   * @private {!Object.<*>}
44
   */
45
  this.parameters_ = {};
46
};
47

48

49
/**
50
 * @return {!webdriver.CommandName} This command's name.
51
 */
52
webdriver.Command.prototype.getName = function() {
53
  return this.name_;
54
};
55

56

57
/**
58
 * Sets a parameter to send with this command.
59
 * @param {string} name The parameter name.
60
 * @param {*} value The parameter value.
61
 * @return {!webdriver.Command} A self reference.
62
 */
63
webdriver.Command.prototype.setParameter = function(name, value) {
64
  this.parameters_[name] = value;
65
  return this;
66
};
67

68

69
/**
70
 * Sets the parameters for this command.
71
 * @param {!Object.<*>} parameters The command parameters.
72
 * @return {!webdriver.Command} A self reference.
73
 */
74
webdriver.Command.prototype.setParameters = function(parameters) {
75
  this.parameters_ = parameters;
76
  return this;
77
};
78

79

80
/**
81
 * Returns a named command parameter.
82
 * @param {string} key The parameter key to look up.
83
 * @return {*} The parameter value, or undefined if it has not been set.
84
 */
85
webdriver.Command.prototype.getParameter = function(key) {
86
  return this.parameters_[key];
87
};
88

89

90
/**
91
 * @return {!Object.<*>} The parameters to send with this command.
92
 */
93
webdriver.Command.prototype.getParameters = function() {
94
  return this.parameters_;
95
};
96

97

98
/**
99
 * Enumeration of predefined names command names that all command processors
100
 * will support.
101
 * @enum {string}
102
 * @suppress {lintChecks}
103
 */
104
// TODO: Delete obsolete command names.
105
webdriver.CommandName = {
106
  GET_SERVER_STATUS: 'getStatus',
107

108
  NEW_SESSION: 'newSession',
109
  GET_SESSIONS: 'getSessions',
110
  DESCRIBE_SESSION: 'getSessionCapabilities',
111

112
  CLOSE: 'close',
113
  QUIT: 'quit',
114

115
  GET_CURRENT_URL: 'getCurrentUrl',
116
  GET: 'get',
117
  GO_BACK: 'goBack',
118
  GO_FORWARD: 'goForward',
119
  REFRESH: 'refresh',
120

121
  ADD_COOKIE: 'addCookie',
122
  GET_COOKIE: 'getCookie',
123
  GET_ALL_COOKIES: 'getCookies',
124
  DELETE_COOKIE: 'deleteCookie',
125
  DELETE_ALL_COOKIES: 'deleteAllCookies',
126

127
  GET_ACTIVE_ELEMENT: 'getActiveElement',
128
  FIND_ELEMENT: 'findElement',
129
  FIND_ELEMENTS: 'findElements',
130
  FIND_CHILD_ELEMENT: 'findChildElement',
131
  FIND_CHILD_ELEMENTS: 'findChildElements',
132

133
  CLEAR_ELEMENT: 'clearElement',
134
  CLICK_ELEMENT: 'clickElement',
135
  SEND_KEYS_TO_ELEMENT: 'sendKeysToElement',
136
  SUBMIT_ELEMENT: 'submitElement',
137

138
  GET_CURRENT_WINDOW_HANDLE: 'getCurrentWindowHandle',
139
  GET_WINDOW_HANDLES: 'getWindowHandles',
140
  GET_WINDOW_POSITION: 'getWindowPosition',
141
  SET_WINDOW_POSITION: 'setWindowPosition',
142
  GET_WINDOW_SIZE: 'getWindowSize',
143
  SET_WINDOW_SIZE: 'setWindowSize',
144
  MAXIMIZE_WINDOW: 'maximizeWindow',
145

146
  SWITCH_TO_WINDOW: 'switchToWindow',
147
  SWITCH_TO_FRAME: 'switchToFrame',
148
  GET_PAGE_SOURCE: 'getPageSource',
149
  GET_TITLE: 'getTitle',
150

151
  EXECUTE_SCRIPT: 'executeScript',
152
  EXECUTE_ASYNC_SCRIPT: 'executeAsyncScript',
153

154
  GET_ELEMENT_TEXT: 'getElementText',
155
  GET_ELEMENT_TAG_NAME: 'getElementTagName',
156
  IS_ELEMENT_SELECTED: 'isElementSelected',
157
  IS_ELEMENT_ENABLED: 'isElementEnabled',
158
  IS_ELEMENT_DISPLAYED: 'isElementDisplayed',
159
  GET_ELEMENT_LOCATION: 'getElementLocation',
160
  GET_ELEMENT_LOCATION_IN_VIEW: 'getElementLocationOnceScrolledIntoView',
161
  GET_ELEMENT_SIZE: 'getElementSize',
162
  GET_ELEMENT_ATTRIBUTE: 'getElementAttribute',
163
  GET_ELEMENT_VALUE_OF_CSS_PROPERTY: 'getElementValueOfCssProperty',
164
  ELEMENT_EQUALS: 'elementEquals',
165

166
  SCREENSHOT: 'screenshot',
167
  TAKE_ELEMENT_SCREENSHOT: 'takeElementScreenshot',
168
  IMPLICITLY_WAIT: 'implicitlyWait',
169
  SET_SCRIPT_TIMEOUT: 'setScriptTimeout',
170
  SET_TIMEOUT: 'setTimeout',
171

172
  ACCEPT_ALERT: 'acceptAlert',
173
  DISMISS_ALERT: 'dismissAlert',
174
  GET_ALERT_TEXT: 'getAlertText',
175
  SET_ALERT_TEXT: 'setAlertValue',
176

177
  EXECUTE_SQL: 'executeSQL',
178
  GET_LOCATION: 'getLocation',
179
  SET_LOCATION: 'setLocation',
180
  GET_APP_CACHE: 'getAppCache',
181
  GET_APP_CACHE_STATUS: 'getStatus',
182
  CLEAR_APP_CACHE: 'clearAppCache',
183
  IS_BROWSER_ONLINE: 'isBrowserOnline',
184
  SET_BROWSER_ONLINE: 'setBrowserOnline',
185

186
  GET_LOCAL_STORAGE_ITEM: 'getLocalStorageItem',
187
  GET_LOCAL_STORAGE_KEYS: 'getLocalStorageKeys',
188
  SET_LOCAL_STORAGE_ITEM: 'setLocalStorageItem',
189
  REMOVE_LOCAL_STORAGE_ITEM: 'removeLocalStorageItem',
190
  CLEAR_LOCAL_STORAGE: 'clearLocalStorage',
191
  GET_LOCAL_STORAGE_SIZE: 'getLocalStorageSize',
192

193
  GET_SESSION_STORAGE_ITEM: 'getSessionStorageItem',
194
  GET_SESSION_STORAGE_KEYS: 'getSessionStorageKey',
195
  SET_SESSION_STORAGE_ITEM: 'setSessionStorageItem',
196
  REMOVE_SESSION_STORAGE_ITEM: 'removeSessionStorageItem',
197
  CLEAR_SESSION_STORAGE: 'clearSessionStorage',
198
  GET_SESSION_STORAGE_SIZE: 'getSessionStorageSize',
199

200
  SET_SCREEN_ORIENTATION: 'setScreenOrientation',
201
  GET_SCREEN_ORIENTATION: 'getScreenOrientation',
202

203
  // These belong to the Advanced user interactions - an element is
204
  // optional for these commands.
205
  CLICK: 'mouseClick',
206
  DOUBLE_CLICK: 'mouseDoubleClick',
207
  MOUSE_DOWN: 'mouseButtonDown',
208
  MOUSE_UP: 'mouseButtonUp',
209
  MOVE_TO: 'mouseMoveTo',
210
  SEND_KEYS_TO_ACTIVE_ELEMENT: 'sendKeysToActiveElement',
211

212
  // These belong to the Advanced Touch API
213
  TOUCH_SINGLE_TAP: 'touchSingleTap',
214
  TOUCH_DOWN: 'touchDown',
215
  TOUCH_UP: 'touchUp',
216
  TOUCH_MOVE: 'touchMove',
217
  TOUCH_SCROLL: 'touchScroll',
218
  TOUCH_DOUBLE_TAP: 'touchDoubleTap',
219
  TOUCH_LONG_PRESS: 'touchLongPress',
220
  TOUCH_FLICK: 'touchFlick',
221

222
  GET_AVAILABLE_LOG_TYPES: 'getAvailableLogTypes',
223
  GET_LOG: 'getLog',
224
  GET_SESSION_LOGS: 'getSessionLogs',
225

226
  // Non-standard commands used by the standalone Selenium server.
227
  UPLOAD_FILE: 'uploadFile'
228
};
229

230

231

232
/**
233
 * Handles the execution of WebDriver {@link webdriver.Command commands}.
234
 * @interface
235
 */
236
webdriver.CommandExecutor = function() {};
237

238

239
/**
240
 * Executes the given `command`. If there is an error executing the
241
 * command, the provided callback will be invoked with the offending error.
242
 * Otherwise, the callback will be invoked with a null Error and non-null
243
 * {@link bot.response.ResponseObject} object.
244
 * @param {!webdriver.Command} command The command to execute.
245
 * @return {!goog.Promise<!bot.response.ResponseObject>} A promise
246
 *     that will be fulfilled with the command result.
247
 */
248
webdriver.CommandExecutor.prototype.execute = goog.abstractMethod;
249

250