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 * @return {!webdriver.Capabilities} A basic set of capabilities for
250 * PhantomJS.
251 */
252webdriver.Capabilities.phantomjs = function() {
253 return new webdriver.Capabilities().
254 set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.PHANTOM_JS);
255};
256
257
258/**
259 * @return {!webdriver.Capabilities} A basic set of capabilities for Safari.
260 */
261webdriver.Capabilities.safari = function() {
262 return new webdriver.Capabilities().
263 set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.SAFARI);
264};
265
266
267/**
268 * @return {!webdriver.Capabilities} A basic set of capabilities for HTMLUnit.
269 */
270webdriver.Capabilities.htmlunit = function() {
271 return new webdriver.Capabilities().
272 set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.HTMLUNIT);
273};
274
275
276/**
277 * @return {!webdriver.Capabilities} A basic set of capabilities for HTMLUnit
278 * with enabled Javascript.
279 */
280webdriver.Capabilities.htmlunitwithjs = function() {
281 return new webdriver.Capabilities().
282 set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.HTMLUNIT).
283 set(webdriver.Capability.SUPPORTS_JAVASCRIPT, true);
284};
285
286
287/**
288 * @return {!Object} The JSON representation of this instance.
289 * @deprecated Use {@link #serialize} since a component capability may be a
290 * promised value.
291 */
292webdriver.Capabilities.prototype.toJSON = function() {
293 return this.caps_;
294};
295
296
297/**
298 * @return {!Object.<string, ?>} The JSON representation of this instance. Note,
299 * the returned object may contain nested promises that are promised values.
300 * @override
301 */
302webdriver.Capabilities.prototype.serialize = function() {
303 return this.caps_;
304};
305
306
307/**
308 * Merges another set of capabilities into this instance. Any duplicates in
309 * the provided set will override those already set on this instance.
310 * @param {!(webdriver.Capabilities|Object)} other The capabilities to
311 * merge into this instance.
312 * @return {!webdriver.Capabilities} A self reference.
313 */
314webdriver.Capabilities.prototype.merge = function(other) {
315 var caps = other instanceof webdriver.Capabilities ?
316 other.caps_ : other;
317 for (var key in caps) {
318 if (caps.hasOwnProperty(key)) {
319 this.set(key, caps[key]);
320 }
321 }
322 return this;
323};
324
325
326/**
327 * @param {string} key The capability to set.
328 * @param {*} value The capability value. Capability values must be JSON
329 * serializable. Pass {@code null} to unset the capability.
330 * @return {!webdriver.Capabilities} A self reference.
331 */
332webdriver.Capabilities.prototype.set = function(key, value) {
333 if (goog.isDefAndNotNull(value)) {
334 this.caps_[key] = value;
335 } else {
336 delete this.caps_[key];
337 }
338 return this;
339};
340
341
342/**
343 * @param {string} key The capability to return.
344 * @return {*} The capability with the given key, or {@code null} if it has
345 * not been set.
346 */
347webdriver.Capabilities.prototype.get = function(key) {
348 var val = null;
349 if (this.caps_.hasOwnProperty(key)) {
350 val = this.caps_[key];
351 }
352 return goog.isDefAndNotNull(val) ? val : null;
353};
354
355
356/**
357 * @param {string} key The capability to check.
358 * @return {boolean} Whether the specified capability is set.
359 */
360webdriver.Capabilities.prototype.has = function(key) {
361 return !!this.get(key);
362};
363
364
365/**
366 * Sets the logging preferences. Preferences may be specified as a
367 * {@link webdriver.logging.Preferences} instance, or a as a map of log-type to
368 * log-level.
369 * @param {!(webdriver.logging.Preferences|Object.<string, string>)} prefs The
370 * logging preferences.
371 * @return {!webdriver.Capabilities} A self reference.
372 */
373webdriver.Capabilities.prototype.setLoggingPrefs = function(prefs) {
374 return this.set(webdriver.Capability.LOGGING_PREFS, prefs);
375};
376
377
378/**
379 * Sets the proxy configuration for this instance.
380 * @param {webdriver.ProxyConfig} proxy The desired proxy configuration.
381 * @return {!webdriver.Capabilities} A self reference.
382 */
383webdriver.Capabilities.prototype.setProxy = function(proxy) {
384 return this.set(webdriver.Capability.PROXY, proxy);
385};
386
387
388/**
389 * Sets whether native events should be used.
390 * @param {boolean} enabled Whether to enable native events.
391 * @return {!webdriver.Capabilities} A self reference.
392 */
393webdriver.Capabilities.prototype.setEnableNativeEvents = function(enabled) {
394 return this.set(webdriver.Capability.NATIVE_EVENTS, enabled);
395};
396
397
398/**
399 * Sets how elements should be scrolled into view for interaction.
400 * @param {number} behavior The desired scroll behavior: either 0 to align with
401 * the top of the viewport or 1 to align with the bottom.
402 * @return {!webdriver.Capabilities} A self reference.
403 */
404webdriver.Capabilities.prototype.setScrollBehavior = function(behavior) {
405 return this.set(webdriver.Capability.ELEMENT_SCROLL_BEHAVIOR, behavior);
406};
407
408
409/**
410 * Sets the default action to take with an unexpected alert before returning
411 * an error.
412 * @param {string} behavior The desired behavior; should be "accept", "dismiss",
413 * or "ignore". Defaults to "dismiss".
414 * @return {!webdriver.Capabilities} A self reference.
415 */
416webdriver.Capabilities.prototype.setAlertBehavior = function(behavior) {
417 return this.set(webdriver.Capability.UNEXPECTED_ALERT_BEHAVIOR, behavior);
418};