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.logging');
28

29

30

31
/**
32
 * Recognized browser names.
33
 * @enum {string}
34
 * @suppress {lintChecks}
35
 */
36
webdriver.Browser = {
37
  ANDROID: 'android',
38
  CHROME: 'chrome',
39
  FIREFOX: 'firefox',
40
  IE: 'internet explorer',
41
  INTERNET_EXPLORER: 'internet explorer',
42
  EDGE: 'MicrosoftEdge',
43
  IPAD: 'iPad',
44
  IPHONE: 'iPhone',
45
  OPERA: 'opera',
46
  PHANTOM_JS: 'phantomjs',
47
  SAFARI: 'safari',
48
  HTMLUNIT: 'htmlunit'
49
};
50

51

52

53
/**
54
 * Describes how a proxy should be configured for a WebDriver session.
55
 * Proxy configuration object, as defined by the WebDriver wire protocol.
56
 * @typedef {(
57
 *     {proxyType: string}|
58
 *     {proxyType: string,
59
 *      proxyAutoconfigUrl: string}|
60
 *     {proxyType: string,
61
 *      ftpProxy: string,
62
 *      httpProxy: string,
63
 *      sslProxy: string,
64
 *      noProxy: string})}
65
 */
66
webdriver.ProxyConfig;
67

68

69

70
/**
71
 * Common webdriver capability keys.
72
 * @enum {string}
73
 */
74
webdriver.Capability = {
75

76
  /**
77
   * Indicates whether a driver should accept all SSL certs by default. This
78
   * capability only applies when requesting a new session. To query whether
79
   * a driver can handle insecure SSL certs, see {@link #SECURE_SSL}.
80
   */
81
  ACCEPT_SSL_CERTS: 'acceptSslCerts',
82

83

84
  /**
85
   * The browser name. Common browser names are defined in the
86
   * {@link webdriver.Browser} enum.
87
   */
88
  BROWSER_NAME: 'browserName',
89

90
  /**
91
   * Defines how elements should be scrolled into the viewport for interaction.
92
   * This capability will be set to zero (0) if elements are aligned with the
93
   * top of the viewport, or one (1) if aligned with the bottom. The default
94
   * behavior is to align with the top of the viewport.
95
   */
96
  ELEMENT_SCROLL_BEHAVIOR: 'elementScrollBehavior',
97

98
  /**
99
   * Whether the driver is capable of handling modal alerts (e.g. alert,
100
   * confirm, prompt). To define how a driver <i>should</i> handle alerts,
101
   * use {@link #UNEXPECTED_ALERT_BEHAVIOR}.
102
   */
103
  HANDLES_ALERTS: 'handlesAlerts',
104

105
  /**
106
   * Key for the logging driver logging preferences.
107
   */
108
  LOGGING_PREFS: 'loggingPrefs',
109

110
  /**
111
   * Whether this session generates native events when simulating user input.
112
   */
113
  NATIVE_EVENTS: 'nativeEvents',
114

115
  /**
116
   * Describes the platform the browser is running on. Will be one of
117
   * ANDROID, IOS, LINUX, MAC, UNIX, or WINDOWS. When <i>requesting</i> a
118
   * session, ANY may be used to indicate no platform preference (this is
119
   * semantically equivalent to omitting the platform capability).
120
   */
121
  PLATFORM: 'platform',
122

123
  /**
124
   * Describes the proxy configuration to use for a new WebDriver session.
125
   */
126
  PROXY: 'proxy',
127

128
  /** Whether the driver supports changing the browser's orientation. */
129
  ROTATABLE: 'rotatable',
130

131
  /**
132
   * Whether a driver is only capable of handling secure SSL certs. To request
133
   * that a driver accept insecure SSL certs by default, use
134
   * {@link #ACCEPT_SSL_CERTS}.
135
   */
136
  SECURE_SSL: 'secureSsl',
137

138
  /** Whether the driver supports manipulating the app cache. */
139
  SUPPORTS_APPLICATION_CACHE: 'applicationCacheEnabled',
140

141
  /** Whether the driver supports locating elements with CSS selectors. */
142
  SUPPORTS_CSS_SELECTORS: 'cssSelectorsEnabled',
143

144
  /** Whether the browser supports JavaScript. */
145
  SUPPORTS_JAVASCRIPT: 'javascriptEnabled',
146

147
  /** Whether the driver supports controlling the browser's location info. */
148
  SUPPORTS_LOCATION_CONTEXT: 'locationContextEnabled',
149

150
  /** Whether the driver supports taking screenshots. */
151
  TAKES_SCREENSHOT: 'takesScreenshot',
152

153
  /**
154
   * Defines how the driver should handle unexpected alerts. The value should
155
   * be one of "accept", "dismiss", or "ignore.
156
   */
157
  UNEXPECTED_ALERT_BEHAVIOR: 'unexpectedAlertBehavior',
158

159
  /** Defines the browser version. */
160
  VERSION: 'version'
161
};
162

163

164

165
/**
166
 * @param {(webdriver.Capabilities|Object)=} opt_other Another set of
167
 *     capabilities to merge into this instance.
168
 * @constructor
169
 */
170
webdriver.Capabilities = function(opt_other) {
171

172
  /** @private {!Object.<string, ?>} */
173
  this.caps_ = {};
174

175
  if (opt_other) {
176
    this.merge(opt_other);
177
  }
178
};
179

180

181
/**
182
 * @return {!webdriver.Capabilities} A basic set of capabilities for Android.
183
 */
184
webdriver.Capabilities.android = function() {
185
  return new webdriver.Capabilities().
186
      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.ANDROID).
187
      set(webdriver.Capability.PLATFORM, 'ANDROID');
188
};
189

190

191
/**
192
 * @return {!webdriver.Capabilities} A basic set of capabilities for Chrome.
193
 */
194
webdriver.Capabilities.chrome = function() {
195
  return new webdriver.Capabilities().
196
      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.CHROME);
197
};
198

199

200
/**
201
 * @return {!webdriver.Capabilities} A basic set of capabilities for Firefox.
202
 */
203
webdriver.Capabilities.firefox = function() {
204
  return new webdriver.Capabilities().
205
      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.FIREFOX);
206
};
207

208

209
/**
210
 * @return {!webdriver.Capabilities} A basic set of capabilities for
211
 *     Internet Explorer.
212
 */
213
webdriver.Capabilities.ie = function() {
214
  return new webdriver.Capabilities().
215
      set(webdriver.Capability.BROWSER_NAME,
216
          webdriver.Browser.INTERNET_EXPLORER).
217
      set(webdriver.Capability.PLATFORM, 'WINDOWS');
218
};
219

220
/**
221
 * @return {!webdriver.Capabilities} A basic set of capabilities for
222
 *     Microsoft Edge.
223
 */
224
webdriver.Capabilities.edge = function() {
225
  return new webdriver.Capabilities().
226
    set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.EDGE);
227
};
228

229

230
/**
231
 * @return {!webdriver.Capabilities} A basic set of capabilities for iPad.
232
 */
233
webdriver.Capabilities.ipad = function() {
234
  return new webdriver.Capabilities().
235
      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.IPAD).
236
      set(webdriver.Capability.PLATFORM, 'MAC');
237
};
238

239

240
/**
241
 * @return {!webdriver.Capabilities} A basic set of capabilities for iPhone.
242
 */
243
webdriver.Capabilities.iphone = function() {
244
  return new webdriver.Capabilities().
245
      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.IPHONE).
246
      set(webdriver.Capability.PLATFORM, 'MAC');
247
};
248

249

250
/**
251
 * @return {!webdriver.Capabilities} A basic set of capabilities for Opera.
252
 */
253
webdriver.Capabilities.opera = function() {
254
  return new webdriver.Capabilities().
255
      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.OPERA);
256
};
257

258
/**
259
 * @return {!webdriver.Capabilities} A basic set of capabilities for
260
 *     PhantomJS.
261
 */
262
webdriver.Capabilities.phantomjs = function() {
263
  return new webdriver.Capabilities().
264
      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.PHANTOM_JS);
265
};
266

267

268
/**
269
 * @return {!webdriver.Capabilities} A basic set of capabilities for Safari.
270
 */
271
webdriver.Capabilities.safari = function() {
272
  return new webdriver.Capabilities().
273
      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.SAFARI).
274
      set(webdriver.Capability.PLATFORM, 'MAC');
275
};
276

277

278
/**
279
 * @return {!webdriver.Capabilities} A basic set of capabilities for HTMLUnit.
280
 */
281
webdriver.Capabilities.htmlunit = function() {
282
  return new webdriver.Capabilities().
283
      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.HTMLUNIT);
284
};
285

286

287
/**
288
 * @return {!webdriver.Capabilities} A basic set of capabilities for HTMLUnit
289
 *     with enabled Javascript.
290
 */
291
webdriver.Capabilities.htmlunitwithjs = function() {
292
  return new webdriver.Capabilities().
293
      set(webdriver.Capability.BROWSER_NAME, webdriver.Browser.HTMLUNIT).
294
      set(webdriver.Capability.SUPPORTS_JAVASCRIPT, true);
295
};
296

297

298
/**
299
 * @return {!Object.<string, ?>} The JSON representation of this instance. Note,
300
 *    the returned object may contain nested promises that are promised values.
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 `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 `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
};
419

420