# 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 |
22 | goog.provide('webdriver.Browser');
23 | goog.provide('webdriver.Capabilities');
24 | goog.provide('webdriver.Capability');
25 | goog.provide('webdriver.ProxyConfig');
26 |
27 | goog.require('webdriver.Serializable');
28 | goog.require('webdriver.logging');
29 |
30 |
31 |
32 | /**
33 | * Recognized browser names.
34 | * @enum {string}
35 | */
36 | webdriver.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 | */
65 | webdriver.ProxyConfig;
66 |
67 |
68 |
69 | /**
70 | * Common webdriver capability keys.
71 | * @enum {string}
72 | */
73 | webdriver.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 | */
170 | webdriver.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 | };
180 | goog.inherits(webdriver.Capabilities, webdriver.Serializable);
181 |
182 |
183 | /**
184 | * @return {!webdriver.Capabilities} A basic set of capabilities for Android.
185 | */
186 | webdriver.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 | */
196 | webdriver.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 | */
205 | webdriver.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 | */
215 | webdriver.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 | */
226 | webdriver.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 | */
236 | webdriver.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 | */
246 | webdriver.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 | */
255 | webdriver.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 | */
264 | webdriver.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 | */
273 | webdriver.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 | */
283 | webdriver.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 | */
295 | webdriver.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 | */
307 | webdriver.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 | */
325 | webdriver.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 | */
340 | webdriver.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 | */
353 | webdriver.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 | */
366 | webdriver.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 | */
376 | webdriver.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 | */
386 | webdriver.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 | */
397 | webdriver.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 | */
409 | webdriver.Capabilities.prototype.setAlertBehavior = function(behavior) {
410 | return this.set(webdriver.Capability.UNEXPECTED_ALERT_BEHAVIOR, behavior);
411 | };