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
'use strict'
19

20
/**
21
 * @fileoverview Defines types related to describing the capabilities of a
22
 * WebDriver session.
23
 */
24

25
const Symbols = require('./symbols')
26

27
/**
28
 * Recognized browser names.
29
 * @enum {string}
30
 */
31
const Browser = {
32
  CHROME: 'chrome',
33
  EDGE: 'MicrosoftEdge',
34
  FIREFOX: 'firefox',
35
  INTERNET_EXPLORER: 'internet explorer',
36
  SAFARI: 'safari',
37
}
38

39
/**
40
 * Strategies for waiting for [document readiness] after a navigation
41
 * event.
42
 *
43
 * [document readiness]: https://html.spec.whatwg.org/#current-document-readiness
44
 *
45
 * @enum {string}
46
 */
47
const PageLoadStrategy = {
48
  /**
49
   * Indicates WebDriver should not wait on the document readiness state after a
50
   * navigation event.
51
   */
52
  NONE: 'none',
53

54
  /**
55
   * Indicates WebDriver should wait for the document readiness state to
56
   * become "interactive" after navigation.
57
   */
58
  EAGER: 'eager',
59

60
  /**
61
   * Indicates WebDriver should wait for the document readiness state to
62
   * be "complete" after navigation. This is the default page loading strategy.
63
   */
64
  NORMAL: 'normal',
65
}
66

67
/**
68
 * Common platform names. These platforms are not explicitly defined by the
69
 * WebDriver spec, however, their use is encouraged for interoperability.
70
 *
71
 * @enum {string}
72
 * @see <https://w3c.github.io/webdriver/webdriver-spec.html>
73
 */
74
const Platform = {
75
  LINUX: 'linux',
76
  MAC: 'mac',
77
  WINDOWS: 'windows',
78
}
79

80
/**
81
 * Record object defining the timeouts that apply to certain WebDriver actions.
82
 *
83
 * @record
84
 */
85
function Timeouts() {}
86

87
/**
88
 * Defines when, in milliseconds, to interrupt a script that is being
89
 * {@linkplain ./webdriver.IWebDriver#executeScript evaluated}.
90
 * @type {number}
91
 */
92
Timeouts.prototype.script
93

94
/**
95
 * The timeout, in milliseconds, to apply to navigation events along with the
96
 * {@link PageLoadStrategy}.
97
 * @type {number}
98
 */
99
Timeouts.prototype.pageLoad
100

101
/**
102
 * The maximum amount of time, in milliseconds, to spend attempting to
103
 * {@linkplain ./webdriver.IWebDriver#findElement locate} an element on the
104
 * current page.
105
 * @type {number}
106
 */
107
Timeouts.prototype.implicit
108

109
/**
110
 * The possible default actions a WebDriver session can take to respond to
111
 * unhandled user prompts (`window.alert()`, `window.confirm()`, and
112
 * `window.prompt()`).
113
 *
114
 * @enum {string}
115
 */
116
const UserPromptHandler = {
117
  /** All prompts should be silently accepted. */
118
  ACCEPT: 'accept',
119
  /** All prompts should be silently dismissed. */
120
  DISMISS: 'dismiss',
121
  /**
122
   * All prompts should be automatically accepted, but an error should be
123
   * returned to the next (or currently executing) WebDriver command.
124
   */
125
  ACCEPT_AND_NOTIFY: 'accept and notify',
126
  /**
127
   * All prompts should be automatically dismissed, but an error should be
128
   * returned to the next (or currently executing) WebDriver command.
129
   */
130
  DISMISS_AND_NOTIFY: 'dismiss and notify',
131
  /** All prompts should be left unhandled. */
132
  IGNORE: 'ignore',
133
}
134

135
/**
136
 * The standard WebDriver capability keys.
137
 *
138
 * @enum {string}
139
 * @see <https://w3c.github.io/webdriver/webdriver-spec.html#capabilities>
140
 */
141
const Capability = {
142
  /**
143
   * Indicates whether a WebDriver session implicitly trusts otherwise untrusted
144
   * and self-signed TLS certificates during navigation.
145
   */
146
  ACCEPT_INSECURE_TLS_CERTS: 'acceptInsecureCerts',
147

148
  /**
149
   * The browser name. Common browser names are defined in the
150
   * {@link ./capabilities.Browser Browser} enum.
151
   */
152
  BROWSER_NAME: 'browserName',
153

154
  /** Identifies the browser version. */
155
  BROWSER_VERSION: 'browserVersion',
156

157
  /**
158
   * Key for the logging driver logging preferences.
159
   * The browser name. Common browser names are defined in the
160
   * {@link ./capabilities.Browser Browser} enum.
161
   */
162
  LOGGING_PREFS: 'goog:loggingPrefs',
163

164
  /**
165
   * Defines the session's
166
   * {@linkplain ./capabilities.PageLoadStrategy page loading strategy}.
167
   */
168
  PAGE_LOAD_STRATEGY: 'pageLoadStrategy',
169

170
  /**
171
   * Identifies the operating system of the endpoint node. Common values
172
   * recognized by the most WebDriver server implementations are predefined in
173
   * the {@link ./capabilities.Platform Platform} enum.
174
   */
175
  PLATFORM_NAME: 'platformName',
176

177
  /**
178
   * Describes the proxy configuration to use for a new WebDriver session.
179
   */
180
  PROXY: 'proxy',
181

182
  /**
183
   * Indicates whether the remote end supports all of the window resizing and
184
   * positioning commands:
185
   *
186
   * -  {@linkplain ./webdriver.Window#getRect Window.getRect()}
187
   * -  {@linkplain ./webdriver.Window#setRect Window.setRect()}
188
   * -  {@linkplain ./webdriver.Window#maximize Window.maximize()}
189
   * -  {@linkplain ./webdriver.Window#minimize Window.minimize()}
190
   * -  {@linkplain ./webdriver.Window#fullscreen Window.fullscreen()}
191
   */
192
  SET_WINDOW_RECT: 'setWindowRect',
193

194
  /**
195
   * Describes the {@linkplain ./capabilities.Timeouts timeouts} imposed on
196
   * certain session operations.
197
   */
198
  TIMEOUTS: 'timeouts',
199

200
  /**
201
   * Defines how a WebDriver session should
202
   * {@linkplain ./capabilities.UserPromptHandler respond} to unhandled user
203
   * prompts.
204
   */
205
  UNHANDLED_PROMPT_BEHAVIOR: 'unhandledPromptBehavior',
206

207
  /**
208
   * Defines the current session’s strict file interactability.
209
   * Used to upload a file when strict file interactability is on
210
   */
211
  STRICT_FILE_INTERACTABILITY: 'strictFileInteractability',
212

213
  ENABLE_DOWNLOADS: 'se:downloadsEnabled',
214
}
215

216
/**
217
 * Converts a generic hash object to a map.
218
 * @param {!Object<string, ?>} hash The hash object.
219
 * @return {!Map<string, ?>} The converted map.
220
 */
221
function toMap(hash) {
222
  let m = new Map()
223
  for (let key in hash) {
224
    if (Object.prototype.hasOwnProperty.call(hash, key)) {
225
      m.set(key, hash[key])
226
    }
227
  }
228
  return m
229
}
230

231
/**
232
 * Describes a set of capabilities for a WebDriver session.
233
 */
234
class Capabilities {
235
  /**
236
   * @param {(Capabilities|Map<string, ?>|Object)=} other Another set of
237
   *     capabilities to initialize this instance from.
238
   */
239
  constructor(other = undefined) {
240
    if (other instanceof Capabilities) {
241
      other = other.map_
242
    } else if (other && !(other instanceof Map)) {
243
      other = toMap(other)
244
    }
245
    /** @private @const {!Map<string, ?>} */
246
    this.map_ = new Map(other)
247
  }
248

249
  /** @return {number} The number of capabilities set. */
250
  get size() {
251
    return this.map_.size
252
  }
253

254
  /**
255
   * @return {!Capabilities} A basic set of capabilities for Chrome.
256
   */
257
  static chrome() {
258
    return new Capabilities().setBrowserName(Browser.CHROME)
259
  }
260

261
  /**
262
   * @return {!Capabilities} A basic set of capabilities for Microsoft Edge.
263
   */
264
  static edge() {
265
    return new Capabilities().setBrowserName(Browser.EDGE)
266
  }
267

268
  /**
269
   * @return {!Capabilities} A basic set of capabilities for Firefox.
270
   */
271
  static firefox() {
272
    return new Capabilities().setBrowserName(Browser.FIREFOX).set('moz:debuggerAddress', true)
273
  }
274

275
  /**
276
   * @return {!Capabilities} A basic set of capabilities for Internet Explorer.
277
   */
278
  static ie() {
279
    return new Capabilities().setBrowserName(Browser.INTERNET_EXPLORER)
280
  }
281

282
  /**
283
   * @return {!Capabilities} A basic set of capabilities for Safari.
284
   */
285
  static safari() {
286
    return new Capabilities().setBrowserName(Browser.SAFARI)
287
  }
288

289
  /**
290
   * @return {!Object<string, ?>} The JSON representation of this instance.
291
   *     Note, the returned object may contain nested promised values.
292
   * @suppress {checkTypes} Suppress [] access on a struct (state inherited from
293
   *     Map).
294
   */
295
  [Symbols.serialize]() {
296
    return serialize(this)
297
  }
298

299
  /**
300
   * @param {string} key the parameter key to get.
301
   * @return {T} the stored parameter value.
302
   * @template T
303
   */
304
  get(key) {
305
    return this.map_.get(key)
306
  }
307

308
  /**
309
   * @param {string} key the key to test.
310
   * @return {boolean} whether this capability set has the specified key.
311
   */
312
  has(key) {
313
    return this.map_.has(key)
314
  }
315

316
  /**
317
   * @return {!Iterator<string>} an iterator of the keys set.
318
   */
319
  keys() {
320
    return this.map_.keys()
321
  }
322

323
  /**
324
   * Merges another set of capabilities into this instance.
325
   * @param {!(Capabilities|Map<String, ?>|Object<string, ?>)} other The other
326
   *     set of capabilities to merge.
327
   * @return {!Capabilities} A self reference.
328
   */
329
  merge(other) {
330
    if (other) {
331
      let otherMap
332
      if (other instanceof Capabilities) {
333
        otherMap = other.map_
334
      } else if (other instanceof Map) {
335
        otherMap = other
336
      } else {
337
        otherMap = toMap(other)
338
      }
339
      otherMap.forEach((value, key) => {
340
        this.set(key, value)
341
      })
342
      return this
343
    } else {
344
      throw new TypeError('no capabilities provided for merge')
345
    }
346
  }
347

348
  /**
349
   * Deletes an entry from this set of capabilities.
350
   *
351
   * @param {string} key the capability key to delete.
352
   */
353
  delete(key) {
354
    this.map_.delete(key)
355
  }
356

357
  /**
358
   * @param {string} key The capability key.
359
   * @param {*} value The capability value.
360
   * @return {!Capabilities} A self reference.
361
   * @throws {TypeError} If the `key` is not a string.
362
   */
363
  set(key, value) {
364
    if (typeof key !== 'string') {
365
      throw new TypeError('Capability keys must be strings: ' + typeof key)
366
    }
367
    this.map_.set(key, value)
368
    return this
369
  }
370

371
  /**
372
   * Sets whether a WebDriver session should implicitly accept self-signed, or
373
   * other untrusted TLS certificates on navigation.
374
   *
375
   * @param {boolean} accept whether to accept insecure certs.
376
   * @return {!Capabilities} a self reference.
377
   */
378
  setAcceptInsecureCerts(accept) {
379
    return this.set(Capability.ACCEPT_INSECURE_TLS_CERTS, accept)
380
  }
381

382
  /**
383
   * @return {boolean} whether the session is configured to accept insecure
384
   *     TLS certificates.
385
   */
386
  getAcceptInsecureCerts() {
387
    return this.get(Capability.ACCEPT_INSECURE_TLS_CERTS)
388
  }
389

390
  /**
391
   * Sets the name of the target browser.
392
   *
393
   * @param {(Browser|string)} name the browser name.
394
   * @return {!Capabilities} a self reference.
395
   */
396
  setBrowserName(name) {
397
    return this.set(Capability.BROWSER_NAME, name)
398
  }
399

400
  /**
401
   * @return {(string|undefined)} the configured browser name, or undefined if
402
   *     not set.
403
   */
404
  getBrowserName() {
405
    return this.get(Capability.BROWSER_NAME)
406
  }
407

408
  /**
409
   * Sets the desired version of the target browser.
410
   *
411
   * @param {string} version the desired version.
412
   * @return {!Capabilities} a self reference.
413
   */
414
  setBrowserVersion(version) {
415
    return this.set(Capability.BROWSER_VERSION, version)
416
  }
417

418
  /**
419
   * @return {(string|undefined)} the configured browser version, or undefined
420
   *     if not set.
421
   */
422
  getBrowserVersion() {
423
    return this.get(Capability.BROWSER_VERSION)
424
  }
425

426
  /**
427
   * Sets the desired page loading strategy for a new WebDriver session.
428
   *
429
   * @param {PageLoadStrategy} strategy the desired strategy.
430
   * @return {!Capabilities} a self reference.
431
   */
432
  setPageLoadStrategy(strategy) {
433
    return this.set(Capability.PAGE_LOAD_STRATEGY, strategy)
434
  }
435

436
  /**
437
   * Returns the configured page load strategy.
438
   *
439
   * @return {(string|undefined)} the page load strategy.
440
   */
441
  getPageLoadStrategy() {
442
    return this.get(Capability.PAGE_LOAD_STRATEGY)
443
  }
444

445
  /**
446
   * Sets the target platform.
447
   *
448
   * @param {(Platform|string)} platform the target platform.
449
   * @return {!Capabilities} a self reference.
450
   */
451
  setPlatform(platform) {
452
    return this.set(Capability.PLATFORM_NAME, platform)
453
  }
454

455
  /**
456
   * @return {(string|undefined)} the configured platform or undefined if not
457
   *     set.
458
   */
459
  getPlatform() {
460
    return this.get(Capability.PLATFORM_NAME)
461
  }
462

463
  /**
464
   * Sets the logging preferences. Preferences may be specified as a
465
   * {@link ./logging.Preferences} instance, or as a map of log-type to
466
   * log-level.
467
   * @param {!(./logging.Preferences|Object<string>)} prefs The logging
468
   *     preferences.
469
   * @return {!Capabilities} A self reference.
470
   */
471
  setLoggingPrefs(prefs) {
472
    return this.set(Capability.LOGGING_PREFS, prefs)
473
  }
474

475
  /**
476
   * Sets the proxy configuration for this instance.
477
   * @param {proxy.Config} proxy The desired proxy configuration.
478
   * @return {!Capabilities} A self reference.
479
   */
480
  setProxy(proxy) {
481
    return this.set(Capability.PROXY, proxy)
482
  }
483

484
  /**
485
   * @return {(proxy.Config|undefined)} the configured proxy settings, or
486
   *     undefined if not set.
487
   */
488
  getProxy() {
489
    return this.get(Capability.PROXY)
490
  }
491

492
  /**
493
   * Sets the default action to take with an unexpected alert before returning
494
   * an error. If unspecified, WebDriver will default to
495
   * {@link UserPromptHandler.DISMISS_AND_NOTIFY}.
496
   *
497
   * @param {?UserPromptHandler} behavior The way WebDriver should respond to
498
   *     unhandled user prompts.
499
   * @return {!Capabilities} A self reference.
500
   */
501
  setAlertBehavior(behavior) {
502
    return this.set(Capability.UNHANDLED_PROMPT_BEHAVIOR, behavior)
503
  }
504

505
  /**
506
   * @return {(UserPromptHandler|undefined)} the behavior pattern for responding
507
   *     to unhandled user prompts, or undefined if not set.
508
   */
509
  getAlertBehavior() {
510
    return this.get(Capability.UNHANDLED_PROMPT_BEHAVIOR)
511
  }
512

513
  /**
514
   * Sets the boolean flag configuration for this instance.
515
   */
516
  setStrictFileInteractability(strictFileInteractability) {
517
    return this.set(Capability.STRICT_FILE_INTERACTABILITY, strictFileInteractability)
518
  }
519

520
  enableDownloads() {
521
    return this.set(Capability.ENABLE_DOWNLOADS, true)
522
  }
523
}
524

525
/**
526
 * Serializes a capabilities object. This is defined as a standalone function
527
 * so it may be type checked (where Capabilities[Symbols.serialize] has type
528
 * checking disabled since it is defined with [] access on a struct).
529
 *
530
 * @param {!Capabilities} caps The capabilities to serialize.
531
 * @return {!Object<string, ?>} The JSON representation of this instance.
532
 *     Note, the returned object may contain nested promised values.
533
 */
534
function serialize(caps) {
535
  let ret = {}
536
  for (let key of caps.keys()) {
537
    let cap = caps.get(key)
538
    if (cap !== undefined && cap !== null) {
539
      ret[key] = cap
540
    }
541
  }
542
  return ret
543
}
544

545
// PUBLIC API
546

547
module.exports = {
548
  Browser,
549
  Capabilities,
550
  Capability,
551
  PageLoadStrategy,
552
  Platform,
553
  Timeouts,
554
  UserPromptHandler,
555
}
556

557