lib/webdriver/capabilities.js

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