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.logging.Preferences');
25
26
27
28/**
29 * Recognized browser names.
30 * @enum {string}
31 */
32webdriver.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 */
60webdriver.ProxyConfig;
61
62
63
64/**
65 * Common webdriver capability keys.
66 * @enum {string}
67 */
68webdriver.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 */
165webdriver.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 */
179webdriver.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 */
189webdriver.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 */
198webdriver.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 */
208webdriver.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 */
219webdriver.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 */
229webdriver.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 */
239webdriver.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 */
249webdriver.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 */
258webdriver.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 */
267webdriver.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 */
277webdriver.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. */
285webdriver.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 */
297webdriver.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 */
315webdriver.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 */
330webdriver.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 */
343webdriver.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 */
356webdriver.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 */
366webdriver.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 */
376webdriver.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 */
387webdriver.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 */
399webdriver.Capabilities.prototype.setAlertBehavior = function(behavior) {
400 return this.set(webdriver.Capability.UNEXPECTED_ALERT_BEHAVIOR, behavior);
401};