# 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 |
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.Serializable');
25 | goog.require('webdriver.logging.Preferences');
26 |
27 |
28 |
29 | /**
30 | * Recognized browser names.
31 | * @enum {string}
32 | */
33 | webdriver.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 | */
62 | webdriver.ProxyConfig;
63 |
64 |
65 |
66 | /**
67 | * Common webdriver capability keys.
68 | * @enum {string}
69 | */
70 | webdriver.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 | */
167 | webdriver.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 | };
177 | goog.inherits(webdriver.Capabilities, webdriver.Serializable);
178 |
179 |
180 | /**
181 | * @return {!webdriver.Capabilities} A basic set of capabilities for Android.
182 | */
183 | webdriver.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 | */
193 | webdriver.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 | */
202 | webdriver.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 | */
212 | webdriver.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 | */
223 | webdriver.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 | */
233 | webdriver.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 | */
243 | webdriver.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 | */
252 | webdriver.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 | */
261 | webdriver.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 | */
270 | webdriver.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 | */
280 | webdriver.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 | */
292 | webdriver.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 | */
302 | webdriver.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 | */
314 | webdriver.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 | */
332 | webdriver.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 | */
347 | webdriver.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 | */
360 | webdriver.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 | */
373 | webdriver.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 | */
383 | webdriver.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 | */
393 | webdriver.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 | */
404 | webdriver.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 | */
416 | webdriver.Capabilities.prototype.setAlertBehavior = function(behavior) {
417 | return this.set(webdriver.Capability.UNEXPECTED_ALERT_BEHAVIOR, behavior);
418 | };