selenium-webdriver 4.4.0 → 4.6.0

package/lib/util.js

@@ -0,0 +1,52 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+'use strict'
+
+/**
+ * Determines whether a {@code value} should be treated as an object.
+ * @param {?} value The value to test.
+ * @returns {boolean} Whether the value is an object.
+ */
+function isObject(value) {
+  return Object.prototype.toString.call(value) === '[object Object]'
+}
+
+/**
+ * Determines whether a {@code value} should be treated as a promise.
+ * Any object whose "then" property is a function will be considered a promise.
+ *
+ * @param {?} value The value to test.
+ * @return {boolean} Whether the value is a promise.
+ */
+function isPromise(value) {
+  try {
+    // Use array notation so the Closure compiler does not obfuscate away our
+    // contract.
+    return (
+      (typeof value === 'object' || typeof value === 'function') &&
+      typeof value['then'] === 'function'
+    )
+  } catch (ex) {
+    return false
+  }
+}
+
+module.exports = {
+  isObject,
+  isPromise,
+}

package/lib/virtual_authenticator.js

@@ -17,30 +17,37 @@
 
 'use strict'
 
+/**
+ * Protocol for virtual authenticators
+ * @enum {string}
+ */
+const Protocol = {
+  CTAP2: 'ctap2',
+  U2F: 'ctap1/u2f',
+}
+
+/**
+ * AuthenticatorTransport values
+ * @enum {string}
+ */
+const Transport = {
+  BLE: 'ble',
+  USB: 'usb',
+  NFC: 'nfc',
+  INTERNAL: 'internal',
+}
+
 /**
  * Options for the creation of virtual authenticators.
  * @see http://w3c.github.io/webauthn/#sctn-automation
  */
 class VirtualAuthenticatorOptions {
-
-  static Protocol = {
-    "CTAP2": 'ctap2',
-    "U2F": 'ctap1/u2f',
-  }
-
-  static Transport = {
-    "BLE": 'ble',
-    "USB": 'usb',
-    "NFC": 'nfc',
-    "INTERNAL": 'internal',
-  }
-
   /**
    * Constructor to initialise VirtualAuthenticatorOptions object.
    */
   constructor() {
-    this._protocol = VirtualAuthenticatorOptions.Protocol["CTAP2"]
-    this._transport = VirtualAuthenticatorOptions.Transport["USB"]
+    this._protocol = Protocol['CTAP2']
+    this._transport = Transport['USB']
     this._hasResidentKey = false
     this._hasUserVerification = false
     this._isUserConsenting = true
@@ -97,13 +104,12 @@ class VirtualAuthenticatorOptions {
 
   toDict() {
     return {
-      "protocol": this.getProtocol(),
-      "transport": this.getTransport(),
-      "hasResidentKey": this.getHasResidentKey(),
-      "hasUserVerification": this.getHasUserVerification(),
-      "isUserConsenting": this.getIsUserConsenting(),
-      "isUserVerified": this.getIsUserVerified(),
-
+      protocol: this.getProtocol(),
+      transport: this.getTransport(),
+      hasResidentKey: this.getHasResidentKey(),
+      hasUserVerification: this.getHasUserVerification(),
+      isUserConsenting: this.getIsUserConsenting(),
+      isUserVerified: this.getIsUserVerified(),
     }
   }
 }
@@ -163,35 +169,47 @@ class Credential {
    * @param userHandle userHandle associated to the credential. Must be Base64 encoded string.
    * @param privateKey Base64 encoded PKCS
    * @param signCount initial value for a signature counter.
+   * @deprecated This method has been made static. Call it with class name. Example, Credential.createResidentCredential()
    * @returns A resident credential
    */
   createResidentCredential(id, rpId, userHandle, privateKey, signCount) {
     return new Credential(id, true, rpId, userHandle, privateKey, signCount)
   }
 
+  static createResidentCredential(id, rpId, userHandle, privateKey, signCount) {
+    return new Credential(id, true, rpId, userHandle, privateKey, signCount)
+  }
+
   /**
    * Creates a non-resident (i.e. stateless) credential.
    * @param id Unique base64 encoded string.
    * @param rpId Relying party identifier.
    * @param privateKey Base64 encoded PKCS
    * @param signCount initial value for a signature counter.
+   * @deprecated This method has been made static. Call it with class name. Example, Credential.createNonResidentCredential()
    * @returns A non-resident credential
    */
   createNonResidentCredential(id, rpId, privateKey, signCount) {
     return new Credential(id, false, rpId, null, privateKey, signCount)
   }
 
+  static createNonResidentCredential(id, rpId, privateKey, signCount) {
+    return new Credential(id, false, rpId, null, privateKey, signCount)
+  }
+
   toDict() {
     let credentialData = {
-      'credentialId': Buffer.from(this._id).toString('base64url'),
-      'isResidentCredential': this._isResidentCredential,
-      'rpId': this._rpId,
-      'privateKey': Buffer.from(this._privateKey, 'binary').toString('base64url'),
-      'signCount': this._signCount,
+      credentialId: Buffer.from(this._id).toString('base64url'),
+      isResidentCredential: this._isResidentCredential,
+      rpId: this._rpId,
+      privateKey: Buffer.from(this._privateKey, 'binary').toString('base64url'),
+      signCount: this._signCount,
     }
 
     if (this.userHandle() != null) {
-      credentialData['userHandle'] = Buffer.from(this._userHandle).toString('base64url')
+      credentialData['userHandle'] = Buffer.from(this._userHandle).toString(
+        'base64url'
+      )
     }
 
     return credentialData
@@ -204,7 +222,9 @@ class Credential {
     let id = new Uint8Array(Buffer.from(data['credentialId'], 'base64url'))
     let isResidentCredential = data['isResidentCredential']
     let rpId = data['rpId']
-    let privateKey = Buffer.from(data['privateKey'], 'base64url').toString('binary')
+    let privateKey = Buffer.from(data['privateKey'], 'base64url').toString(
+      'binary'
+    )
     let signCount = data['signCount']
     let userHandle
 
@@ -224,7 +244,11 @@ class Credential {
   }
 }
 
+// PUBLIC API
+
 module.exports = {
   Credential,
   VirtualAuthenticatorOptions,
+  Transport,
+  Protocol,
 }

package/lib/webdriver.js

@@ -37,7 +37,9 @@ const { Capabilities } = require('./capabilities')
 const path = require('path')
 const { NoSuchElementError } = require('./error')
 const cdpTargets = ['page', 'browser']
-const Credential = require('./virtual_authenticator').Credential
+const { Credential } = require('./virtual_authenticator')
+const webElement = require('./webelement')
+const { isObject } = require('./util')
 
 // Capability names that are defined in the W3C spec.
 const W3C_CAPABILITY_NAMES = new Set([
@@ -213,7 +215,7 @@ function fromWireValue(driver, value) {
   } else if (ShadowRoot.isId(value)) {
     let id = ShadowRoot.extractId(value)
     value = new ShadowRoot(driver, id)
-  } else if (value && typeof value === 'object') {
+  } else if (isObject(value)) {
     let result = {}
     for (let key in value) {
       if (Object.prototype.hasOwnProperty.call(value, key)) {
@@ -272,7 +274,7 @@ class IWebDriver {
 
   /**
    * @return {!Promise<!Capabilities>} A promise that will resolve with
-   *     the this instance's capabilities.
+   *     the instance's capabilities.
    */
   getCapabilities() {}
 
@@ -453,7 +455,7 @@ class IWebDriver {
    * @return {!(IThenable<T>|WebElementPromise)} A promise that will be
    *     resolved with the first truthy value returned by the condition
    *     function, or rejected if the condition times out. If the input
-   *     input condition is an instance of a {@link WebElementCondition},
+   *     condition is an instance of a {@link WebElementCondition},
    *     the returned value will be a {@link WebElementPromise}.
    * @throws {TypeError} if the provided `condition` is not a valid type.
    * @template T
@@ -584,7 +586,7 @@ class IWebDriver {
   findElements(locator) {} // eslint-disable-line
 
   /**
-   * Takes a screenshot of the current page. The driver makes a best effort to
+   * Takes a screenshot of the current page. The driver makes the best effort to
    * return a screenshot of the following, in order of preference:
    *
    * 1. Entire page
@@ -618,17 +620,17 @@ class IWebDriver {
    * Takes a PDF of the current page. The driver makes a best effort to
    * return a PDF based on the provided parameters.
    *
-   * @param {{orientation: (string|undefined),
-   *         scale: (number|undefined),
-   *         background: (boolean|undefined)
-   *         width: (number|undefined)
-   *         height: (number|undefined)
-   *         top: (number|undefined)
-   *         bottom: (number|undefined)
-   *         left: (number|undefined)
-   *         right: (number|undefined)
-   *         shrinkToFit: (boolean|undefined)
-   *         pageRanges: (<Array>|undefined)}} options.
+   * @param {{orientation:(string|undefined),
+   *         scale:(number|undefined),
+   *         background:(boolean|undefined),
+   *         width:(number|undefined),
+   *         height:(number|undefined),
+   *         top:(number|undefined),
+   *         bottom:(number|undefined),
+   *         left:(number|undefined),
+   *         right:(number|undefined),
+   *         shrinkToFit:(boolean|undefined),
+   *         pageRanges:(Array|undefined)}} options
    */
   printPage(options) {} // eslint-disable-line
 }
@@ -713,10 +715,9 @@ class WebDriver {
   static createSession(executor, capabilities, onQuit = undefined) {
     let cmd = new command.Command(command.Name.NEW_SESSION)
 
-    // For OSS remote ends.
-    cmd.setParameter('desiredCapabilities', capabilities)
     // For W3C remote ends.
     cmd.setParameter('capabilities', {
+      firstMatch: [{}],
       alwaysMatch: filterNonW3CCaps(capabilities),
     })
 
@@ -1311,7 +1312,7 @@ class WebDriver {
 
   /**
    * Sets a listener for Fetch.authRequired event from CDP
-   * If event is triggered, it enter username and password
+   * If event is triggered, it enters username and password
    * and allows the test to move forward
    * @param {string} username
    * @param {string} password
@@ -1530,7 +1531,7 @@ class WebDriver {
 
   /**
    * Adds a virtual authenticator with the given options.
-   * @param options VirtualAuthenticatorOptions object to set authenticator optons.
+   * @param options VirtualAuthenticatorOptions object to set authenticator options.
    */
   async addVirtualAuthenticator(options) {
     this.authenticatorId_ = await this.execute(
@@ -2058,7 +2059,7 @@ class Window {
   }
 
   /**
-   * Retrieves the a rect describing the current top-level window's size and
+   * Retrieves a rect describing the current top-level window's size and
    * position.
    *
    * @return {!Promise<{x: number, y: number, width: number, height: number}>}
@@ -2382,7 +2383,7 @@ class TargetLocator {
 
 const LEGACY_ELEMENT_ID_KEY = 'ELEMENT'
 const ELEMENT_ID_KEY = 'element-6066-11e4-a52e-4f735466cecf'
-const SHADOWROOT_ID_KEY = 'shadow-6066-11e4-a52e-4f735466cecf'
+const SHADOW_ROOT_ID_KEY = 'shadow-6066-11e4-a52e-4f735466cecf'
 
 /**
  * Represents a DOM element. WebElements can be found by searching from the
@@ -2427,14 +2428,7 @@ class WebElement {
    * @throws {TypeError} if the object is not a valid encoded ID.
    */
   static extractId(obj) {
-    if (obj && typeof obj === 'object') {
-      if (typeof obj[ELEMENT_ID_KEY] === 'string') {
-        return obj[ELEMENT_ID_KEY]
-      } else if (typeof obj[LEGACY_ELEMENT_ID_KEY] === 'string') {
-        return obj[LEGACY_ELEMENT_ID_KEY]
-      }
-    }
-    throw new TypeError('object is not a WebElement ID')
+    return webElement.extractId(obj)
   }
 
   /**
@@ -2442,12 +2436,7 @@ class WebElement {
    * @return {boolean} whether the object is a valid encoded WebElement ID.
    */
   static isId(obj) {
-    return (
-      obj &&
-      typeof obj === 'object' &&
-      (typeof obj[ELEMENT_ID_KEY] === 'string' ||
-        typeof obj[LEGACY_ELEMENT_ID_KEY] === 'string')
-    )
+    return webElement.isId(obj)
   }
 
   /**
@@ -2550,7 +2539,7 @@ class WebElement {
   }
 
   /**
-   * Locates all of the descendants of this element that match the given search
+   * Locates all the descendants of this element that match the given search
    * criteria.
    *
    * @param {!(by.By|Function)} locator The locator strategy to use when
@@ -2717,7 +2706,7 @@ class WebElement {
    * the value of the property with the same name is returned. If neither value
    * is set, null is returned (for example, the "value" property of a textarea
    * element). The "style" attribute is converted as best can be to a
-   * text representation with a trailing semi-colon. The following are deemed to
+   * text representation with a trailing semicolon. The following are deemed to
    * be "boolean" attributes and will return either "true" or null:
    *
    * async, autofocus, autoplay, checked, compact, complete, controls, declare,
@@ -2992,8 +2981,8 @@ class ShadowRoot {
    */
   static extractId(obj) {
     if (obj && typeof obj === 'object') {
-      if (typeof obj[SHADOWROOT_ID_KEY] === 'string') {
-        return obj[SHADOWROOT_ID_KEY]
+      if (typeof obj[SHADOW_ROOT_ID_KEY] === 'string') {
+        return obj[SHADOW_ROOT_ID_KEY]
       }
     }
     throw new TypeError('object is not a ShadowRoot ID')
@@ -3007,7 +2996,7 @@ class ShadowRoot {
     return (
       obj &&
       typeof obj === 'object' &&
-      typeof obj[SHADOWROOT_ID_KEY] === 'string'
+      typeof obj[SHADOW_ROOT_ID_KEY] === 'string'
     )
   }
 
@@ -3083,7 +3072,7 @@ class ShadowRoot {
   }
 
   /**
-   * Locates all of the descendants of this element that match the given search
+   * Locates all the descendants of this element that match the given search
    * criteria.
    *
    * @param {!(by.By|Function)} locator The locator strategy to use when

package/lib/webelement.js

@@ -0,0 +1,66 @@
+// Licensed to the Software Freedom Conservancy (SFC) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The SFC licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+'use strict'
+const { isObject } = require('./util')
+
+/**
+ * @fileoverview Defines some common methods used for WebElements.
+ */
+
+const LEGACY_ELEMENT_ID_KEY = 'ELEMENT'
+const ELEMENT_ID_KEY = 'element-6066-11e4-a52e-4f735466cecf'
+
+/**
+ * Contains logic about WebElements.
+ */
+/**
+ * @param {?} obj the object to test.
+ * @return {boolean} whether the object is a valid encoded WebElement ID.
+ */
+function isId(obj) {
+  return (
+    isObject(obj) &&
+    (typeof obj[ELEMENT_ID_KEY] === 'string' ||
+      typeof obj[LEGACY_ELEMENT_ID_KEY] === 'string')
+  )
+}
+
+/**
+ * Extracts the encoded WebElement ID from the object.
+ *
+ * @param {?} obj The object to extract the ID from.
+ * @return {string} the extracted ID.
+ * @throws {TypeError} if the object is not a valid encoded ID.
+ */
+function extractId(obj) {
+  if (isObject(obj)) {
+    if (typeof obj[ELEMENT_ID_KEY] === 'string') {
+      return obj[ELEMENT_ID_KEY]
+    } else if (typeof obj[LEGACY_ELEMENT_ID_KEY] === 'string') {
+      return obj[LEGACY_ELEMENT_ID_KEY]
+    }
+  }
+  throw new TypeError('object is not a WebElement ID')
+}
+
+// PUBLIC API
+
+module.exports = {
+  isId,
+  extractId,
+}

package/net/index.js

@@ -76,11 +76,7 @@ function getAddress(family = 'IPv4') {
  * @return {(string|undefined)} The IP address or undefined if not available.
  */
 function getLoopbackAddress(family = 'IPv4') {
-  let address = getIPAddress(true, family)
-  if (address === '127.0.0.1') {
-    address = 'localhost'
-  }
-  return address
+  return getIPAddress(true, family)
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "selenium-webdriver",
-  "version": "4.4.0",
+  "version": "4.6.0",
   "description": "The official WebDriver JavaScript bindings from the Selenium project",
   "license": "Apache-2.0",
   "keywords": [
@@ -20,7 +20,7 @@
     "url": "https://github.com/SeleniumHQ/selenium.git"
   },
   "engines": {
-    "node": ">= 10.15.0"
+    "node": ">= 14.20.0"
   },
   "dependencies": {
     "jszip": "^3.10.0",

package/remote/index.js

@@ -23,7 +23,7 @@ const url = require('url')
 
 const httpUtil = require('../http/util')
 const io = require('../io')
-const exec = require('../io/exec')
+const { exec } = require('../io/exec')
 const { Zip } = require('../io/zip')
 const cmd = require('../lib/command')
 const input = require('../lib/input')

package/testing/index.js

@@ -88,7 +88,7 @@ function warn(msg) {
  * Extracts the browsers for a test suite to target from the `SELENIUM_BROWSER`
  * environment variable.
  *
- * @return {{name: string, version: string, platform: string}[]} the browsers to target.
+ * @return {{name: string, version: string, platform: string}}[] the browsers to target.
  */
 function getBrowsersToTestFromEnv() {
   let browsers = process.env['SELENIUM_BROWSER']