lib/webdriver/command.js

1// Copyright 2011 Software Freedom Conservancy. All Rights Reserved.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15/**
16 * @fileoverview Contains several classes for handling commands.
17 */
18
19goog.provide('webdriver.Command');
20goog.provide('webdriver.CommandExecutor');
21goog.provide('webdriver.CommandName');
22
23
24
25/**
26 * Describes a command to be executed by the WebDriverJS framework.
27 * @param {!webdriver.CommandName} name The name of this command.
28 * @constructor
29 */
30webdriver.Command = function(name) {
31
32 /**
33 * The name of this command.
34 * @private {!webdriver.CommandName}
35 */
36 this.name_ = name;
37
38 /**
39 * The parameters to this command.
40 * @private {!Object.<*>}
41 */
42 this.parameters_ = {};
43};
44
45
46/**
47 * @return {!webdriver.CommandName} This command's name.
48 */
49webdriver.Command.prototype.getName = function() {
50 return this.name_;
51};
52
53
54/**
55 * Sets a parameter to send with this command.
56 * @param {string} name The parameter name.
57 * @param {*} value The parameter value.
58 * @return {!webdriver.Command} A self reference.
59 */
60webdriver.Command.prototype.setParameter = function(name, value) {
61 this.parameters_[name] = value;
62 return this;
63};
64
65
66/**
67 * Sets the parameters for this command.
68 * @param {!Object.<*>} parameters The command parameters.
69 * @return {!webdriver.Command} A self reference.
70 */
71webdriver.Command.prototype.setParameters = function(parameters) {
72 this.parameters_ = parameters;
73 return this;
74};
75
76
77/**
78 * Returns a named command parameter.
79 * @param {string} key The parameter key to look up.
80 * @return {*} The parameter value, or undefined if it has not been set.
81 */
82webdriver.Command.prototype.getParameter = function(key) {
83 return this.parameters_[key];
84};
85
86
87/**
88 * @return {!Object.<*>} The parameters to send with this command.
89 */
90webdriver.Command.prototype.getParameters = function() {
91 return this.parameters_;
92};
93
94
95/**
96 * Enumeration of predefined names command names that all command processors
97 * will support.
98 * @enum {string}
99 */
100// TODO: Delete obsolete command names.
101webdriver.CommandName = {
102 GET_SERVER_STATUS: 'getStatus',
103
104 NEW_SESSION: 'newSession',
105 GET_SESSIONS: 'getSessions',
106 DESCRIBE_SESSION: 'getSessionCapabilities',
107
108 CLOSE: 'close',
109 QUIT: 'quit',
110
111 GET_CURRENT_URL: 'getCurrentUrl',
112 GET: 'get',
113 GO_BACK: 'goBack',
114 GO_FORWARD: 'goForward',
115 REFRESH: 'refresh',
116
117 ADD_COOKIE: 'addCookie',
118 GET_COOKIE: 'getCookie',
119 GET_ALL_COOKIES: 'getCookies',
120 DELETE_COOKIE: 'deleteCookie',
121 DELETE_ALL_COOKIES: 'deleteAllCookies',
122
123 GET_ACTIVE_ELEMENT: 'getActiveElement',
124 FIND_ELEMENT: 'findElement',
125 FIND_ELEMENTS: 'findElements',
126 FIND_CHILD_ELEMENT: 'findChildElement',
127 FIND_CHILD_ELEMENTS: 'findChildElements',
128
129 CLEAR_ELEMENT: 'clearElement',
130 CLICK_ELEMENT: 'clickElement',
131 SEND_KEYS_TO_ELEMENT: 'sendKeysToElement',
132 SUBMIT_ELEMENT: 'submitElement',
133
134 GET_CURRENT_WINDOW_HANDLE: 'getCurrentWindowHandle',
135 GET_WINDOW_HANDLES: 'getWindowHandles',
136 GET_WINDOW_POSITION: 'getWindowPosition',
137 SET_WINDOW_POSITION: 'setWindowPosition',
138 GET_WINDOW_SIZE: 'getWindowSize',
139 SET_WINDOW_SIZE: 'setWindowSize',
140 MAXIMIZE_WINDOW: 'maximizeWindow',
141
142 SWITCH_TO_WINDOW: 'switchToWindow',
143 SWITCH_TO_FRAME: 'switchToFrame',
144 GET_PAGE_SOURCE: 'getPageSource',
145 GET_TITLE: 'getTitle',
146
147 EXECUTE_SCRIPT: 'executeScript',
148 EXECUTE_ASYNC_SCRIPT: 'executeAsyncScript',
149
150 GET_ELEMENT_TEXT: 'getElementText',
151 GET_ELEMENT_TAG_NAME: 'getElementTagName',
152 IS_ELEMENT_SELECTED: 'isElementSelected',
153 IS_ELEMENT_ENABLED: 'isElementEnabled',
154 IS_ELEMENT_DISPLAYED: 'isElementDisplayed',
155 GET_ELEMENT_LOCATION: 'getElementLocation',
156 GET_ELEMENT_LOCATION_IN_VIEW: 'getElementLocationOnceScrolledIntoView',
157 GET_ELEMENT_SIZE: 'getElementSize',
158 GET_ELEMENT_ATTRIBUTE: 'getElementAttribute',
159 GET_ELEMENT_VALUE_OF_CSS_PROPERTY: 'getElementValueOfCssProperty',
160 ELEMENT_EQUALS: 'elementEquals',
161
162 SCREENSHOT: 'screenshot',
163 IMPLICITLY_WAIT: 'implicitlyWait',
164 SET_SCRIPT_TIMEOUT: 'setScriptTimeout',
165 SET_TIMEOUT: 'setTimeout',
166
167 ACCEPT_ALERT: 'acceptAlert',
168 DISMISS_ALERT: 'dismissAlert',
169 GET_ALERT_TEXT: 'getAlertText',
170 SET_ALERT_TEXT: 'setAlertValue',
171
172 EXECUTE_SQL: 'executeSQL',
173 GET_LOCATION: 'getLocation',
174 SET_LOCATION: 'setLocation',
175 GET_APP_CACHE: 'getAppCache',
176 GET_APP_CACHE_STATUS: 'getStatus',
177 CLEAR_APP_CACHE: 'clearAppCache',
178 IS_BROWSER_ONLINE: 'isBrowserOnline',
179 SET_BROWSER_ONLINE: 'setBrowserOnline',
180
181 GET_LOCAL_STORAGE_ITEM: 'getLocalStorageItem',
182 GET_LOCAL_STORAGE_KEYS: 'getLocalStorageKeys',
183 SET_LOCAL_STORAGE_ITEM: 'setLocalStorageItem',
184 REMOVE_LOCAL_STORAGE_ITEM: 'removeLocalStorageItem',
185 CLEAR_LOCAL_STORAGE: 'clearLocalStorage',
186 GET_LOCAL_STORAGE_SIZE: 'getLocalStorageSize',
187
188 GET_SESSION_STORAGE_ITEM: 'getSessionStorageItem',
189 GET_SESSION_STORAGE_KEYS: 'getSessionStorageKey',
190 SET_SESSION_STORAGE_ITEM: 'setSessionStorageItem',
191 REMOVE_SESSION_STORAGE_ITEM: 'removeSessionStorageItem',
192 CLEAR_SESSION_STORAGE: 'clearSessionStorage',
193 GET_SESSION_STORAGE_SIZE: 'getSessionStorageSize',
194
195 SET_SCREEN_ORIENTATION: 'setScreenOrientation',
196 GET_SCREEN_ORIENTATION: 'getScreenOrientation',
197
198 // These belong to the Advanced user interactions - an element is
199 // optional for these commands.
200 CLICK: 'mouseClick',
201 DOUBLE_CLICK: 'mouseDoubleClick',
202 MOUSE_DOWN: 'mouseButtonDown',
203 MOUSE_UP: 'mouseButtonUp',
204 MOVE_TO: 'mouseMoveTo',
205 SEND_KEYS_TO_ACTIVE_ELEMENT: 'sendKeysToActiveElement',
206
207 // These belong to the Advanced Touch API
208 TOUCH_SINGLE_TAP: 'touchSingleTap',
209 TOUCH_DOWN: 'touchDown',
210 TOUCH_UP: 'touchUp',
211 TOUCH_MOVE: 'touchMove',
212 TOUCH_SCROLL: 'touchScroll',
213 TOUCH_DOUBLE_TAP: 'touchDoubleTap',
214 TOUCH_LONG_PRESS: 'touchLongPress',
215 TOUCH_FLICK: 'touchFlick',
216
217 GET_AVAILABLE_LOG_TYPES: 'getAvailableLogTypes',
218 GET_LOG: 'getLog',
219 GET_SESSION_LOGS: 'getSessionLogs',
220
221 // Non-standard commands used by the standalone Selenium server.
222 UPLOAD_FILE: 'uploadFile'
223};
224
225
226
227/**
228 * Handles the execution of WebDriver {@link webdriver.Command commands}.
229 * @interface
230 */
231webdriver.CommandExecutor = function() {};
232
233
234/**
235 * Executes the given {@code command}. If there is an error executing the
236 * command, the provided callback will be invoked with the offending error.
237 * Otherwise, the callback will be invoked with a null Error and non-null
238 * {@link bot.response.ResponseObject} object.
239 * @param {!webdriver.Command} command The command to execute.
240 * @param {function(Error, !bot.response.ResponseObject=)} callback the function
241 * to invoke when the command response is ready.
242 */
243webdriver.CommandExecutor.prototype.execute = goog.abstractMethod;