1 | // Copyright 2013 Software Freedom Conservancy |
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 Defines the webdriver.Capabilities class. |
17 | */ |
18 | |
19 | goog.provide('webdriver.Browser'); |
20 | goog.provide('webdriver.Capabilities'); |
21 | goog.provide('webdriver.Capability'); |
22 | goog.provide('webdriver.ProxyConfig'); |
23 | |
24 | goog.require('webdriver.logging.Preferences'); |
25 | |
26 | |
27 | |
28 | /** |
29 | * Recognized browser names. |
30 | * @enum {string} |
31 | */ |
32 | webdriver.Browser = { |
33 | ANDROID: 'android', |
34 | CHROME: 'chrome', |
35 | FIREFOX: 'firefox', |
36 | INTERNET_EXPLORER: 'internet explorer', |
37 | IPAD: 'iPad', |
38 | IPHONE: 'iPhone', |
39 | OPERA: 'opera', |
40 | PHANTOM_JS: 'phantomjs', |
41 | SAFARI: 'safari', |
42 | HTMLUNIT: 'htmlunit' |
43 | }; |
44 | |
45 | |
46 | |
47 | /** |
48 | * Describes how a proxy should be configured for a WebDriver session. |
49 | * Proxy configuration object, as defined by the WebDriver wire protocol. |
50 | * @typedef {( |
51 | * {proxyType: string}| |
52 | * {proxyType: string, |
53 | * proxyAutoconfigUrl: string}| |
54 | * {proxyType: string, |
55 | * ftpProxy: string, |
56 | * httpProxy: string, |
57 | * sslProxy: string, |
58 | * noProxy: string})} |
59 | */ |
60 | webdriver.ProxyConfig; |
61 | |
62 | |
63 | |
64 | /** |
65 | * Common webdriver capability keys. |
66 | * @enum {string} |
67 | */ |
68 | webdriver.Capability = { |
69 | |
70 | /** |
71 | * Indicates whether a driver should accept all SSL certs by default. This |
72 | * capability only applies when requesting a new session. To query whether |
73 | * a driver can handle insecure SSL certs, see |
74 | * {@link webdriver.Capability.SECURE_SSL}. |
75 | */ |
76 | ACCEPT_SSL_CERTS: 'acceptSslCerts', |
77 | |
78 | |
79 | /** |
80 | * The browser name. Common browser names are defined in the |
81 | * {@link webdriver.Browser} enum. |
82 | */ |
83 | BROWSER_NAME: 'browserName', |
84 | |
85 | /** |
86 | * Defines how elements should be scrolled into the viewport for interaction. |
87 | * This capability will be set to zero (0) if elements are aligned with the |
88 | * top of the viewport, or one (1) if aligned with the bottom. The default |
89 | * behavior is to align with the top of the viewport. |
90 | */ |
91 | ELEMENT_SCROLL_BEHAVIOR: 'elementScrollBehavior', |
92 | |
93 | /** |
94 | * Whether the driver is capable of handling modal alerts (e.g. alert, |
95 | * confirm, prompt). To define how a driver <i>should</i> handle alerts, |
96 | * use {@link webdriver.Capability.UNEXPECTED_ALERT_BEHAVIOR}. |
97 | */ |
98 | HANDLES_ALERTS: 'handlesAlerts', |
99 | |
100 | /** |
101 | * Key for the logging driver logging preferences. |
102 | */ |
103 | LOGGING_PREFS: 'loggingPrefs', |
104 | |
105 | /** |
106 | * Whether this session generates native events when simulating user input. |
107 | */ |
108 | NATIVE_EVENTS: 'nativeEvents', |
109 | |
110 | /** |
111 | * Describes the platform the browser is running on. Will be one of |
112 | * ANDROID, IOS, LINUX, MAC, UNIX, or WINDOWS. When <i>requesting</i> a |
113 | * session, ANY may be used to indicate no platform preference (this is |
114 | * semantically equivalent to omitting the platform capability). |
115 | */ |
116 | PLATFORM: 'platform', |
117 | |
118 | /** |
119 | * Describes the proxy configuration to use for a new WebDriver session. |
120 | */ |
121 | PROXY: 'proxy', |
122 | |
123 | /** Whether the driver supports changing the brower's orientation. */ |
124 | ROTATABLE: 'rotatable', |
125 | |
126 | /** |
127 | * Whether a driver is only capable of handling secure SSL certs. To request |
128 | * that a driver accept insecure SSL certs by default, use |
129 | * {@link webdriver.Capability.ACCEPT_SSL_CERTS}. |
130 | */ |
131 | SECURE_SSL: 'secureSsl', |
132 | |
133 | /** Whether the driver supports manipulating the app cache. */ |
134 | SUPPORTS_APPLICATION_CACHE: 'applicationCacheEnabled', |
135 | |
136 | /** Whether the driver supports locating elements with CSS selectors. */ |
137 | SUPPORTS_CSS_SELECTORS: 'cssSelectorsEnabled', |
138 | |
139 | /** Whether the browser supports JavaScript. */ |
140 | SUPPORTS_JAVASCRIPT: 'javascriptEnabled', |
141 | |
142 | /** Whether the driver supports controlling the browser's location info. */ |
143 | SUPPORTS_LOCATION_CONTEXT: 'locationContextEnabled', |
144 | |
145 | /** Whether the driver supports taking screenshots. */ |
146 | TAKES_SCREENSHOT: 'takesScreenshot', |
147 | |
148 | /** |
149 | * Defines how the driver should handle unexpected alerts. The value should |
150 | * be one of "accept", "dismiss", or "ignore. |
151 | */ |
152 | UNEXPECTED_ALERT_BEHAVIOR: 'unexpectedAlertBehavior', |
153 | |
154 | /** Defines the browser version. */ |
155 | VERSION: 'version' |
156 | }; |
157 | |
158 | |
159 | |
160 | /** |
161 | * @param {(webdriver.Capabilities|Object)=} opt_other Another set of |
162 | * capabilities to merge into this instance. |
163 | * @constructor |
164 | */ |
165 | webdriver.Capabilities = function(opt_other) { |
166 | |
167 | /** @private {!Object} */ |
168 | this.caps_ = {}; |
169 | |
170 | if (opt_other) { |
171 | this.merge(opt_other); |
172 | } |
173 | }; |
174 | |
175 | |
176 | /** |
177 | * @return {!webdriver.Capabilities} A basic set of capabilities for Android. |
178 | */ |
179 | webdriver.Capabilities.android = function() { |
180 | return new webdriver.Capabilities(). |
181 | set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.ANDROID). |
182 | set(webdriver.Capability.PLATFORM, 'ANDROID'); |
183 | }; |
184 | |
185 | |
186 | /** |
187 | * @return {!webdriver.Capabilities} A basic set of capabilities for Chrome. |
188 | */ |
189 | webdriver.Capabilities.chrome = function() { |
190 | return new webdriver.Capabilities(). |
191 | set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.CHROME); |
192 | }; |
193 | |
194 | |
195 | /** |
196 | * @return {!webdriver.Capabilities} A basic set of capabilities for Firefox. |
197 | */ |
198 | webdriver.Capabilities.firefox = function() { |
199 | return new webdriver.Capabilities(). |
200 | set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.FIREFOX); |
201 | }; |
202 | |
203 | |
204 | /** |
205 | * @return {!webdriver.Capabilities} A basic set of capabilities for |
206 | * Internet Explorer. |
207 | */ |
208 | webdriver.Capabilities.ie = function() { |
209 | return new webdriver.Capabilities(). |
210 | set(webdriver.Capability.BROWSER_NAME, |
211 | webdriver.Browser.INTERNET_EXPLORER). |
212 | set(webdriver.Capability.PLATFORM, 'WINDOWS'); |
213 | }; |
214 | |
215 | |
216 | /** |
217 | * @return {!webdriver.Capabilities} A basic set of capabilities for iPad. |
218 | */ |
219 | webdriver.Capabilities.ipad = function() { |
220 | return new webdriver.Capabilities(). |
221 | set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.IPAD). |
222 | set(webdriver.Capability.PLATFORM, 'MAC'); |
223 | }; |
224 | |
225 | |
226 | /** |
227 | * @return {!webdriver.Capabilities} A basic set of capabilities for iPhone. |
228 | */ |
229 | webdriver.Capabilities.iphone = function() { |
230 | return new webdriver.Capabilities(). |
231 | set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.IPHONE). |
232 | set(webdriver.Capability.PLATFORM, 'MAC'); |
233 | }; |
234 | |
235 | |
236 | /** |
237 | * @return {!webdriver.Capabilities} A basic set of capabilities for Opera. |
238 | */ |
239 | webdriver.Capabilities.opera = function() { |
240 | return new webdriver.Capabilities(). |
241 | set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.OPERA); |
242 | }; |
243 | |
244 | |
245 | /** |
246 | * @return {!webdriver.Capabilities} A basic set of capabilities for |
247 | * PhantomJS. |
248 | */ |
249 | webdriver.Capabilities.phantomjs = function() { |
250 | return new webdriver.Capabilities(). |
251 | set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.PHANTOM_JS); |
252 | }; |
253 | |
254 | |
255 | /** |
256 | * @return {!webdriver.Capabilities} A basic set of capabilities for Safari. |
257 | */ |
258 | webdriver.Capabilities.safari = function() { |
259 | return new webdriver.Capabilities(). |
260 | set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.SAFARI); |
261 | }; |
262 | |
263 | |
264 | /** |
265 | * @return {!webdriver.Capabilities} A basic set of capabilities for HTMLUnit. |
266 | */ |
267 | webdriver.Capabilities.htmlunit = function() { |
268 | return new webdriver.Capabilities(). |
269 | set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.HTMLUNIT); |
270 | }; |
271 | |
272 | |
273 | /** |
274 | * @return {!webdriver.Capabilities} A basic set of capabilities for HTMLUnit |
275 | * with enabled Javascript. |
276 | */ |
277 | webdriver.Capabilities.htmlunitwithjs = function() { |
278 | return new webdriver.Capabilities(). |
279 | set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.HTMLUNIT). |
280 | set(webdriver.Capability.SUPPORTS_JAVASCRIPT, true); |
281 | }; |
282 | |
283 | |
284 | /** @return {!Object} The JSON representation of this instance. */ |
285 | webdriver.Capabilities.prototype.toJSON = function() { |
286 | return this.caps_; |
287 | }; |
288 | |
289 | |
290 | /** |
291 | * Merges another set of capabilities into this instance. Any duplicates in |
292 | * the provided set will override those already set on this instance. |
293 | * @param {!(webdriver.Capabilities|Object)} other The capabilities to |
294 | * merge into this instance. |
295 | * @return {!webdriver.Capabilities} A self reference. |
296 | */ |
297 | webdriver.Capabilities.prototype.merge = function(other) { |
298 | var caps = other instanceof webdriver.Capabilities ? |
299 | other.caps_ : other; |
300 | for (var key in caps) { |
301 | if (caps.hasOwnProperty(key)) { |
302 | this.set(key, caps[key]); |
303 | } |
304 | } |
305 | return this; |
306 | }; |
307 | |
308 | |
309 | /** |
310 | * @param {string} key The capability to set. |
311 | * @param {*} value The capability value. Capability values must be JSON |
312 | * serializable. Pass {@code null} to unset the capability. |
313 | * @return {!webdriver.Capabilities} A self reference. |
314 | */ |
315 | webdriver.Capabilities.prototype.set = function(key, value) { |
316 | if (goog.isDefAndNotNull(value)) { |
317 | this.caps_[key] = value; |
318 | } else { |
319 | delete this.caps_[key]; |
320 | } |
321 | return this; |
322 | }; |
323 | |
324 | |
325 | /** |
326 | * @param {string} key The capability to return. |
327 | * @return {*} The capability with the given key, or {@code null} if it has |
328 | * not been set. |
329 | */ |
330 | webdriver.Capabilities.prototype.get = function(key) { |
331 | var val = null; |
332 | if (this.caps_.hasOwnProperty(key)) { |
333 | val = this.caps_[key]; |
334 | } |
335 | return goog.isDefAndNotNull(val) ? val : null; |
336 | }; |
337 | |
338 | |
339 | /** |
340 | * @param {string} key The capability to check. |
341 | * @return {boolean} Whether the specified capability is set. |
342 | */ |
343 | webdriver.Capabilities.prototype.has = function(key) { |
344 | return !!this.get(key); |
345 | }; |
346 | |
347 | |
348 | /** |
349 | * Sets the logging preferences. Preferences may be specified as a |
350 | * {@link webdriver.logging.Preferences} instance, or a as a map of log-type to |
351 | * log-level. |
352 | * @param {!(webdriver.logging.Preferences|Object.<string, string>)} prefs The |
353 | * logging preferences. |
354 | * @return {!webdriver.Capabilities} A self reference. |
355 | */ |
356 | webdriver.Capabilities.prototype.setLoggingPrefs = function(prefs) { |
357 | return this.set(webdriver.Capability.LOGGING_PREFS, prefs); |
358 | }; |
359 | |
360 | |
361 | /** |
362 | * Sets the proxy configuration for this instance. |
363 | * @param {webdriver.ProxyConfig} proxy The desired proxy configuration. |
364 | * @return {!webdriver.Capabilities} A self reference. |
365 | */ |
366 | webdriver.Capabilities.prototype.setProxy = function(proxy) { |
367 | return this.set(webdriver.Capability.PROXY, proxy); |
368 | }; |
369 | |
370 | |
371 | /** |
372 | * Sets whether native events should be used. |
373 | * @param {boolean} enabled Whether to enable native events. |
374 | * @return {!webdriver.Capabilities} A self reference. |
375 | */ |
376 | webdriver.Capabilities.prototype.setEnableNativeEvents = function(enabled) { |
377 | return this.set(webdriver.Capability.NATIVE_EVENTS, enabled); |
378 | }; |
379 | |
380 | |
381 | /** |
382 | * Sets how elements should be scrolled into view for interaction. |
383 | * @param {number} behavior The desired scroll behavior: either 0 to align with |
384 | * the top of the viewport or 1 to align with the bottom. |
385 | * @return {!webdriver.Capabilities} A self reference. |
386 | */ |
387 | webdriver.Capabilities.prototype.setScrollBehavior = function(behavior) { |
388 | return this.set(webdriver.Capability.ELEMENT_SCROLL_BEHAVIOR, behavior); |
389 | }; |
390 | |
391 | |
392 | /** |
393 | * Sets the default action to take with an unexpected alert before returning |
394 | * an error. |
395 | * @param {string} behavior The desired behavior; should be "accept", "dismiss", |
396 | * or "ignore". Defaults to "dismiss". |
397 | * @return {!webdriver.Capabilities} A self reference. |
398 | */ |
399 | webdriver.Capabilities.prototype.setAlertBehavior = function(behavior) { |
400 | return this.set(webdriver.Capability.UNEXPECTED_ALERT_BEHAVIOR, behavior); |
401 | }; |