lib/webdriver/capabilities.js

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