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');
22
23
24
25/**
26 * Recognized browser names.
27 * @enum {string}
28 */
29webdriver.Browser = {
30 ANDROID: 'android',
31 CHROME: 'chrome',
32 FIREFOX: 'firefox',
33 INTERNET_EXPLORER: 'internet explorer',
34 IPAD: 'iPad',
35 IPHONE: 'iPhone',
36 OPERA: 'opera',
37 PHANTOM_JS: 'phantomjs',
38 SAFARI: 'safari',
39 HTMLUNIT: 'htmlunit'
40};
41
42
43
44/**
45 * Common webdriver capability keys.
46 * @enum {string}
47 */
48webdriver.Capability = {
49
50 /**
51 * Indicates whether a driver should accept all SSL certs by default. This
52 * capability only applies when requesting a new session. To query whether
53 * a driver can handle insecure SSL certs, see
54 * {@link webdriver.Capability.SECURE_SSL}.
55 */
56 ACCEPT_SSL_CERTS: 'acceptSslCerts',
57
58
59 /**
60 * The browser name. Common browser names are defined in the
61 * {@link webdriver.Browser} enum.
62 */
63 BROWSER_NAME: 'browserName',
64
65 /**
66 * Whether the driver is capable of handling modal alerts (e.g. alert,
67 * confirm, prompt). To define how a driver <i>should</i> handle alerts,
68 * use {@link webdriver.Capability.UNEXPECTED_ALERT_BEHAVIOR}.
69 */
70 HANDLES_ALERTS: 'handlesAlerts',
71
72 /**
73 * Key for the logging driver logging preferences.
74 */
75 LOGGING_PREFS: 'loggingPrefs',
76
77 /**
78 * Describes the platform the browser is running on. Will be one of
79 * ANDROID, IOS, LINUX, MAC, UNIX, or WINDOWS. When <i>requesting</i> a
80 * session, ANY may be used to indicate no platform preference (this is
81 * semantically equivalent to omitting the platform capability).
82 */
83 PLATFORM: 'platform',
84
85 /**
86 * Describes the proxy configuration to use for a new WebDriver session.
87 */
88 PROXY: 'proxy',
89
90 /** Whether the driver supports changing the brower's orientation. */
91 ROTATABLE: 'rotatable',
92
93 /**
94 * Whether a driver is only capable of handling secure SSL certs. To request
95 * that a driver accept insecure SSL certs by default, use
96 * {@link webdriver.Capability.ACCEPT_SSL_CERTS}.
97 */
98 SECURE_SSL: 'secureSsl',
99
100 /** Whether the driver supports manipulating the app cache. */
101 SUPPORTS_APPLICATION_CACHE: 'applicationCacheEnabled',
102
103 /**
104 * Whether the driver supports controlling the browser's internet
105 * connectivity.
106 */
107 SUPPORTS_BROWSER_CONNECTION: 'browserConnectionEnabled',
108
109 /** Whether the driver supports locating elements with CSS selectors. */
110 SUPPORTS_CSS_SELECTORS: 'cssSelectorsEnabled',
111
112 /** Whether the browser supports JavaScript. */
113 SUPPORTS_JAVASCRIPT: 'javascriptEnabled',
114
115 /** Whether the driver supports controlling the browser's location info. */
116 SUPPORTS_LOCATION_CONTEXT: 'locationContextEnabled',
117
118 /** Whether the driver supports taking screenshots. */
119 TAKES_SCREENSHOT: 'takesScreenshot',
120
121 /**
122 * Defines how the driver should handle unexpected alerts. The value should
123 * be one of "accept", "dismiss", or "ignore.
124 */
125 UNEXPECTED_ALERT_BEHAVIOR: 'unexpectedAlertBehavior',
126
127 /** Defines the browser version. */
128 VERSION: 'version'
129};
130
131
132
133/**
134 * @param {(webdriver.Capabilities|Object)=} opt_other Another set of
135 * capabilities to merge into this instance.
136 * @constructor
137 */
138webdriver.Capabilities = function(opt_other) {
139
140 /** @private {!Object} */
141 this.caps_ = {};
142
143 if (opt_other) {
144 this.merge(opt_other);
145 }
146};
147
148
149/**
150 * @return {!webdriver.Capabilities} A basic set of capabilities for Android.
151 */
152webdriver.Capabilities.android = function() {
153 return new webdriver.Capabilities().
154 set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.ANDROID).
155 set(webdriver.Capability.PLATFORM, 'ANDROID');
156};
157
158
159/**
160 * @return {!webdriver.Capabilities} A basic set of capabilities for Chrome.
161 */
162webdriver.Capabilities.chrome = function() {
163 return new webdriver.Capabilities().
164 set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.CHROME);
165};
166
167
168/**
169 * @return {!webdriver.Capabilities} A basic set of capabilities for Firefox.
170 */
171webdriver.Capabilities.firefox = function() {
172 return new webdriver.Capabilities().
173 set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.FIREFOX);
174};
175
176
177/**
178 * @return {!webdriver.Capabilities} A basic set of capabilities for
179 * Internet Explorer.
180 */
181webdriver.Capabilities.ie = function() {
182 return new webdriver.Capabilities().
183 set(webdriver.Capability.BROWSER_NAME,
184 webdriver.Browser.INTERNET_EXPLORER).
185 set(webdriver.Capability.PLATFORM, 'WINDOWS');
186};
187
188
189/**
190 * @return {!webdriver.Capabilities} A basic set of capabilities for iPad.
191 */
192webdriver.Capabilities.ipad = function() {
193 return new webdriver.Capabilities().
194 set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.IPAD).
195 set(webdriver.Capability.PLATFORM, 'MAC');
196};
197
198
199/**
200 * @return {!webdriver.Capabilities} A basic set of capabilities for iPhone.
201 */
202webdriver.Capabilities.iphone = function() {
203 return new webdriver.Capabilities().
204 set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.IPHONE).
205 set(webdriver.Capability.PLATFORM, 'MAC');
206};
207
208
209/**
210 * @return {!webdriver.Capabilities} A basic set of capabilities for Opera.
211 */
212webdriver.Capabilities.opera = function() {
213 return new webdriver.Capabilities().
214 set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.OPERA);
215};
216
217
218/**
219 * @return {!webdriver.Capabilities} A basic set of capabilities for
220 * PhantomJS.
221 */
222webdriver.Capabilities.phantomjs = function() {
223 return new webdriver.Capabilities().
224 set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.PHANTOM_JS);
225};
226
227
228/**
229 * @return {!webdriver.Capabilities} A basic set of capabilities for Safari.
230 */
231webdriver.Capabilities.safari = function() {
232 return new webdriver.Capabilities().
233 set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.SAFARI);
234};
235
236
237/**
238 * @return {!webdriver.Capabilities} A basic set of capabilities for HTMLUnit.
239 */
240webdriver.Capabilities.htmlunit = function() {
241 return new webdriver.Capabilities().
242 set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.HTMLUNIT);
243};
244
245
246/**
247 * @return {!webdriver.Capabilities} A basic set of capabilities for HTMLUnit
248 * with enabled Javascript.
249 */
250webdriver.Capabilities.htmlunitwithjs = function() {
251 return new webdriver.Capabilities().
252 set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.HTMLUNIT).
253 set(webdriver.Capability.SUPPORTS_JAVASCRIPT, true);
254};
255
256
257/** @return {!Object} The JSON representation of this instance. */
258webdriver.Capabilities.prototype.toJSON = function() {
259 return this.caps_;
260};
261
262
263/**
264 * Merges another set of capabilities into this instance. Any duplicates in
265 * the provided set will override those already set on this instance.
266 * @param {!(webdriver.Capabilities|Object)} other The capabilities to
267 * merge into this instance.
268 * @return {!webdriver.Capabilities} A self reference.
269 */
270webdriver.Capabilities.prototype.merge = function(other) {
271 var caps = other instanceof webdriver.Capabilities ?
272 other.caps_ : other;
273 for (var key in caps) {
274 if (caps.hasOwnProperty(key)) {
275 this.set(key, caps[key]);
276 }
277 }
278 return this;
279};
280
281
282/**
283 * @param {string} key The capability to set.
284 * @param {*} value The capability value. Capability values must be JSON
285 * serializable. Pass {@code null} to unset the capability.
286 * @return {!webdriver.Capabilities} A self reference.
287 */
288webdriver.Capabilities.prototype.set = function(key, value) {
289 if (goog.isDefAndNotNull(value)) {
290 this.caps_[key] = value;
291 } else {
292 delete this.caps_[key];
293 }
294 return this;
295};
296
297
298/**
299 * @param {string} key The capability to return.
300 * @return {*} The capability with the given key, or {@code null} if it has
301 * not been set.
302 */
303webdriver.Capabilities.prototype.get = function(key) {
304 var val = null;
305 if (this.caps_.hasOwnProperty(key)) {
306 val = this.caps_[key];
307 }
308 return goog.isDefAndNotNull(val) ? val : null;
309};
310
311
312/**
313 * @param {string} key The capability to check.
314 * @return {boolean} Whether the specified capability is set.
315 */
316webdriver.Capabilities.prototype.has = function(key) {
317 return !!this.get(key);
318};