selenium-webdriver 4.19.0 → 4.20.0

package/CHANGES.md

@@ -1,3 +1,18 @@
+## 4.20.0
+
+- Add CDP for Chrome 124 and remove 121
+- [bidi] Update capture screenshot APIs to include all parameters and remove scroll parameter (
+  #13744)
+- [bidi] Implement functionality to retrieve all top-level browsing contexts
+- Set browserName by default when browserOptions are used
+- Implement fullPageScreenshot functionality for Firefox (#13301)
+- Nightly JS builds are now pushed to GitHub packages
+- Making Selenium Manager a thin wrapper (#13853)
+  - This change has been made to make it easier to maintain and improve, the interface has
+    changed and if users were invoking it, they might experience issues. Selenium Manager is
+    still in beta and these type of changes are expected.
+- [bidi] Update browsing context create method (#13766)
+
 ## 4.19.0
 
 - Add CDP for Chrome 123 and remove 120

package/bidi/addInterceptParameters.js

@@ -29,6 +29,13 @@ class AddInterceptParameters {
     }
   }
 
+  /**
+   * Adds a URL pattern to intercept.
+   *
+   * @param {UrlPattern} pattern - The URL pattern to add.
+   * @returns {AddInterceptParameters} - Returns the current instance of the class AddInterceptParameters for chaining.
+   * @throws {Error} - Throws an error if the pattern is not an instance of UrlPattern.
+   */
   urlPattern(pattern) {
     if (!(pattern instanceof UrlPattern)) {
       throw new Error(`Pattern must be an instance of UrlPattern. Received: '${pattern})'`)
@@ -37,6 +44,13 @@ class AddInterceptParameters {
     return this
   }
 
+  /**
+   * Adds array of URL patterns to intercept.
+   *
+   * @param {UrlPattern[]} patterns - An array of UrlPattern instances representing the URL patterns to intercept.
+   * @returns {AddInterceptParameters} - Returns the instance of AddInterceptParameters for chaining.
+   * @throws {Error} - Throws an error if the pattern is not an instance of UrlPattern.
+   */
   urlPatterns(patterns) {
     patterns.forEach((pattern) => {
       if (!(pattern instanceof UrlPattern)) {
@@ -47,8 +61,15 @@ class AddInterceptParameters {
     return this
   }
 
+  /**
+   * Adds string URL to intercept.
+   *
+   * @param {string} pattern - The URL pattern to be added.
+   * @returns {AddInterceptParameters} - Returns the instance of AddInterceptParameters for chaining..
+   * @throws {Error} - If the pattern is not an instance of String.
+   */
   urlStringPattern(pattern) {
-    if (!(pattern instanceof String)) {
+    if (typeof pattern !== 'string') {
       throw new Error(`Pattern must be an instance of String. Received:'${pattern}'`)
     }
 
@@ -56,9 +77,14 @@ class AddInterceptParameters {
     return this
   }
 
+  /**
+   * Adds array of string URLs to intercept.
+   * @param {string[]} patterns - An array of URL string patterns.
+   * @returns {this} - Returns the instance of AddInterceptParameters for chaining.
+   */
   urlStringPatterns(patterns) {
     patterns.forEach((pattern) => {
-      if (!(pattern instanceof String)) {
+      if (typeof pattern !== 'string') {
         throw new Error(`Pattern must be an instance of String. Received:'${pattern}'`)
       }
       this.#urlPatterns.push({ type: 'string', pattern: pattern })

package/bidi/browser.js

@@ -15,6 +15,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
+/**
+ * Represents the commands and events under Browser Module.
+ * Described in https://w3c.github.io/webdriver-bidi/#module-browser
+ */
 class Browser {
   constructor(driver) {
     this._driver = driver
@@ -28,6 +32,10 @@ class Browser {
     this.bidi = await this._driver.getBidi()
   }
 
+  /**
+   * Creates a new user context.
+   * @returns {Promise<string>} A promise that resolves to the user context id.
+   */
   async createUserContext() {
     const command = {
       method: 'browser.createUserContext',
@@ -39,6 +47,10 @@ class Browser {
     return response.result.userContext
   }
 
+  /**
+   * Gets the list of all user contexts.
+   * @returns {Promise<string[]>} A promise that resolves to an array of user context ids.
+   */
   async getUserContexts() {
     const command = {
       method: 'browser.getUserContexts',
@@ -58,6 +70,11 @@ class Browser {
     return userContexts
   }
 
+  /**
+   * Removes a user context.
+   * @param {string} userContext The user context id to be removed.
+   * @returns {Promise<void>}
+   */
   async removeUserContext(userContext) {
     const command = {
       method: 'browser.removeUserContext',

package/bidi/browsingContext.js

@@ -19,7 +19,13 @@ const { InvalidArgumentError, NoSuchFrameError } = require('../lib/error')
 const { BrowsingContextInfo } = require('./browsingContextTypes')
 const { SerializationOptions, ReferenceValue, RemoteValue } = require('./protocolValue')
 const { WebElement } = require('../lib/webdriver')
+const { CaptureScreenshotParameters } = require('./captureScreenshotParameters')
+const { CreateContextParameters } = require('./createContextParameters')
 
+/**
+ * Represents the locator to locate nodes in the browsing context.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-browsingContext-Locator.
+ */
 class Locator {
   static Type = Object.freeze({
     CSS: 'css',
@@ -41,14 +47,35 @@ class Locator {
     this.#maxDepth = maxDepth
   }
 
+  /**
+   * Creates a new Locator object with CSS selector type.
+   *
+   * @param {string} value - The CSS selector value.
+   * @returns {Locator} A new Locator object with CSS selector type.
+   */
   static css(value) {
     return new Locator(Locator.Type.CSS, value)
   }
 
+  /**
+   * Creates a new Locator object with the given XPath value.
+   *
+   * @param {string} value - The XPath value.
+   * @returns {Locator} A new Locator object.
+   */
   static xpath(value) {
     return new Locator(Locator.Type.XPATH, value)
   }
 
+  /**
+   * Creates a new Locator object with the specified inner text value.
+   *
+   * @param {string} value - The inner text value to locate.
+   * @param {boolean|undefined} [ignoreCase] - Whether to ignore the case when matching the inner text value.
+   * @param {string|undefined} [matchType] - The type of matching to perform (full or partial).
+   * @param {number|undefined} [maxDepth] - The maximum depth to search for the inner text value.
+   * @returns {Locator} A new Locator object with the specified inner text value.
+   */
   static innerText(value, ignoreCase = undefined, matchType = undefined, maxDepth = undefined) {
     return new Locator(Locator.Type.INNER_TEXT, value, ignoreCase, matchType, maxDepth)
   }
@@ -66,6 +93,12 @@ class Locator {
   }
 }
 
+/**
+ * Represents the contains under BrowsingContext module commands.
+ * Described in https://w3c.github.io/webdriver-bidi/#module-browsingContext
+ * Each browsing context command requires a browsing context id.
+ * Hence, this class represent browsing context lifecycle.
+ */
 class BrowsingContext {
   constructor(driver) {
     this._driver = driver
@@ -78,11 +111,19 @@ class BrowsingContext {
     return this._id
   }
 
-  async init({ browsingContextId, type, referenceContext }) {
+  async init({ browsingContextId = undefined, type = undefined, createParameters = undefined }) {
     if (!(await this._driver.getCapabilities()).get('webSocketUrl')) {
       throw Error('WebDriver instance must support BiDi protocol')
     }
 
+    if (browsingContextId === undefined && type === undefined && createParameters === undefined) {
+      throw Error('Either BrowsingContextId or Type or CreateParameters must be provided')
+    }
+
+    if (type === undefined && createParameters !== undefined) {
+      throw Error('Type must be provided with CreateParameters')
+    }
+
     if (type !== undefined && !['window', 'tab'].includes(type)) {
       throw Error(`Valid types are 'window' & 'tab'. Received: ${type}`)
     }
@@ -90,22 +131,33 @@ class BrowsingContext {
     this.bidi = await this._driver.getBidi()
     this._id =
       browsingContextId === undefined
-        ? (await this.create(type, referenceContext))['result']['context']
+        ? (await this.create(type, createParameters))['result']['context']
         : browsingContextId
   }
 
   /**
-   * Creates a browsing context for the given type and referenceContext
+   * Creates a browsing context for the given type with the given parameters
    */
-  async create(type, referenceContext) {
+  async create(type, createParameters = undefined) {
+    if (createParameters !== undefined && (!createParameters) instanceof CreateContextParameters) {
+      throw Error(`Pass in the instance of CreateContextParameters. Received: ${createParameters}`)
+    }
+
+    let parameters = new Map()
+    parameters.set('type', type)
+
+    if (createParameters !== undefined) {
+      createParameters.asMap().forEach((value, key) => {
+        parameters.set(key, value)
+      })
+    }
+
     const params = {
       method: 'browsingContext.create',
-      params: {
-        type: type,
-        referenceContext: referenceContext,
-      },
+      params: Object.fromEntries(parameters),
     }
-    return await this.bidi.send(params)
+    const res = await this.bidi.send(params)
+    return res
   }
 
   /**
@@ -153,6 +205,27 @@ class BrowsingContext {
     return new BrowsingContextInfo(result['context'], result['url'], result['children'], result['parent'])
   }
 
+  /**
+   * @returns {Promise<Array<BrowsingContextInfo>>} A Promise that resolves to an array of BrowsingContextInfo objects representing the top-level browsing contexts.
+   */
+  async getTopLevelContexts() {
+    const params = {
+      method: 'browsingContext.getTree',
+      params: {},
+    }
+
+    let result = await this.bidi.send(params)
+    if ('error' in result) {
+      throw Error(result['error'])
+    }
+
+    const contexts = result['result']['contexts']
+    const browsingContexts = contexts.map((context) => {
+      return new BrowsingContextInfo(context['id'], context['url'], context['children'], context['parent'])
+    })
+    return browsingContexts
+  }
+
   /**
    * Closes the browsing context
    * @returns {Promise<void>}
@@ -203,12 +276,34 @@ class BrowsingContext {
     return new PrintResult(response.result.data)
   }
 
-  async captureScreenshot() {
+  /**
+   * Captures a screenshot of the browsing context.
+   *
+   * @param {CaptureScreenshotParameters|undefined} [captureScreenshotParameters] - Optional parameters for capturing the screenshot.
+   * @returns {Promise<string>} - A promise that resolves to the base64-encoded string representation of the captured screenshot.
+   * @throws {InvalidArgumentError} - If the provided captureScreenshotParameters is not an instance of CaptureScreenshotParameters.
+   */
+  async captureScreenshot(captureScreenshotParameters = undefined) {
+    if (
+      captureScreenshotParameters !== undefined &&
+      !(captureScreenshotParameters instanceof CaptureScreenshotParameters)
+    ) {
+      throw new InvalidArgumentError(
+        `Pass in a CaptureScreenshotParameters object. Received: ${captureScreenshotParameters}`,
+      )
+    }
+
+    const screenshotParams = new Map()
+    screenshotParams.set('context', this._id)
+    if (captureScreenshotParameters !== undefined) {
+      captureScreenshotParameters.asMap().forEach((value, key) => {
+        screenshotParams.set(key, value)
+      })
+    }
+
     let params = {
       method: 'browsingContext.captureScreenshot',
-      params: {
-        context: this._id,
-      },
+      params: Object.fromEntries(screenshotParams),
     }
 
     const response = await this.bidi.send(params)
@@ -231,15 +326,18 @@ class BrowsingContext {
       },
     }
 
-    console.log(JSON.stringify(params))
-
     const response = await this.bidi.send(params)
-    console.log(JSON.stringify(response))
     this.checkErrorInScreenshot(response)
     return response['result']['data']
   }
 
-  async captureElementScreenshot(sharedId, handle = undefined, scrollIntoView = undefined) {
+  /**
+   * Captures a screenshot of a specific element within the browsing context.
+   * @param {string} sharedId - The shared ID of the element to capture.
+   * @param {string} [handle] - The handle of the element to capture (optional).
+   * @returns {Promise<string>} A promise that resolves to the base64-encoded screenshot data.
+   */
+  async captureElementScreenshot(sharedId, handle = undefined) {
     let params = {
       method: 'browsingContext.captureScreenshot',
       params: {
@@ -250,7 +348,6 @@ class BrowsingContext {
             sharedId: sharedId,
             handle: handle,
           },
-          scrollIntoView: scrollIntoView,
         },
       },
     }
@@ -274,6 +371,11 @@ class BrowsingContext {
     }
   }
 
+  /**
+   * Activates and focuses the top-level browsing context.
+   * @returns {Promise<void>} A promise that resolves when the browsing context is activated.
+   * @throws {Error} If there is an error while activating the browsing context.
+   */
   async activate() {
     const params = {
       method: 'browsingContext.activate',
@@ -288,6 +390,13 @@ class BrowsingContext {
     }
   }
 
+  /**
+   * Handles a user prompt in the browsing context.
+   *
+   * @param {boolean} [accept] - Optional. Indicates whether to accept or dismiss the prompt.
+   * @param {string} [userText] - Optional. The text to enter.
+   * @throws {Error} If an error occurs while handling the user prompt.
+   */
   async handleUserPrompt(accept = undefined, userText = undefined) {
     const params = {
       method: 'browsingContext.handleUserPrompt',
@@ -304,6 +413,15 @@ class BrowsingContext {
     }
   }
 
+  /**
+   * Reloads the current browsing context.
+   *
+   * @param {boolean} [ignoreCache] - Whether to ignore the cache when reloading.
+   * @param {string} [readinessState] - The readiness state to wait for before returning.
+   *        Valid readiness states are 'none', 'interactive', and 'complete'.
+   * @returns {Promise<NavigateResult>} - A promise that resolves to the result of the reload operation.
+   * @throws {Error} - If an invalid readiness state is provided.
+   */
   async reload(ignoreCache = undefined, readinessState = undefined) {
     if (readinessState !== undefined && !['none', 'interactive', 'complete'].includes(readinessState)) {
       throw Error(`Valid readiness states are 'none', 'interactive' & 'complete'. Received: ${readinessState}`)
@@ -322,6 +440,13 @@ class BrowsingContext {
     return new NavigateResult(navigateResult['url'], navigateResult['navigation'])
   }
 
+  /**
+   * Sets the viewport size and device pixel ratio for the browsing context.
+   * @param {number} width - The width of the viewport.
+   * @param {number} height - The height of the viewport.
+   * @param {number} [devicePixelRatio] - The device pixel ratio (optional)
+   * @throws {Error} If an error occurs while setting the viewport.
+   */
   async setViewport(width, height, devicePixelRatio = undefined) {
     const params = {
       method: 'browsingContext.setViewport',
@@ -337,6 +462,12 @@ class BrowsingContext {
     }
   }
 
+  /**
+   * Traverses the browsing context history by a given delta.
+   *
+   * @param {number} delta - The delta value to traverse the history. A positive value moves forward, while a negative value moves backward.
+   * @returns {Promise<void>} - A promise that resolves when the history traversal is complete.
+   */
   async traverseHistory(delta) {
     const params = {
       method: 'browsingContext.traverseHistory',
@@ -348,14 +479,38 @@ class BrowsingContext {
     await this.bidi.send(params)
   }
 
+  /**
+   * Moves the browsing context forward by one step in the history.
+   * @returns {Promise<void>} A promise that resolves when the browsing context has moved forward.
+   */
   async forward() {
     await this.traverseHistory(1)
   }
 
+  /**
+   * Navigates the browsing context to the previous page in the history.
+   * @returns {Promise<void>} A promise that resolves when the navigation is complete.
+   */
   async back() {
     await this.traverseHistory(-1)
   }
 
+  /**
+   * Locates nodes in the browsing context.
+   *
+   * @param {Locator} locator - The locator object used to locate the nodes.
+   * @param {number} [maxNodeCount] - The maximum number of nodes to locate (optional).
+   * @param {string} [ownership] - The ownership type of the nodes (optional).
+   * @param {string} [sandbox] - The sandbox name for locating nodes (optional).
+   * @param {SerializationOptions} [serializationOptions] - The serialization options for locating nodes (optional).
+   * @param {ReferenceValue[]} [startNodes] - The array of start nodes for locating nodes (optional).
+   * @returns {Promise<RemoteValue[]>} - A promise that resolves to the arrays of located nodes.
+   * @throws {Error} - If the locator is not an instance of Locator.
+   * @throws {Error} - If the serializationOptions is provided but not an instance of SerializationOptions.
+   * @throws {Error} - If the ownership is provided but not 'root' or 'none'.
+   * @throws {Error} - If the startNodes is provided but not an array of ReferenceValue objects.
+   * @throws {Error} - If any of the startNodes is not an instance of ReferenceValue.
+   */
   async locateNodes(
     locator,
     maxNodeCount = undefined,
@@ -415,6 +570,16 @@ class BrowsingContext {
     return remoteValues
   }
 
+  /**
+   * Locates a single node in the browsing context.
+   *
+   * @param {Locator} locator - The locator used to find the node.
+   * @param {string} [ownership] - The ownership of the node (optional).
+   * @param {string} [sandbox] - The sandbox of the node (optional).
+   * @param {SerializationOptions} [serializationOptions] - The serialization options for the node (optional).
+   * @param {Array} [startNodes] - The starting nodes for the search (optional).
+   * @returns {Promise<RemoteValue>} - A promise that resolves to the located node.
+   */
   async locateNode(
     locator,
     ownership = undefined,
@@ -442,26 +607,44 @@ class BrowsingContext {
   }
 }
 
+/**
+ * Represents the result of a navigation operation.
+ */
 class NavigateResult {
   constructor(url, navigationId) {
     this._url = url
     this._navigationId = navigationId
   }
 
+  /**
+   * Gets the URL of the navigated page.
+   * @returns {string} The URL of the navigated page.
+   */
   get url() {
     return this._url
   }
 
+  /**
+   * Gets the ID of the navigation operation.
+   * @returns {number} The ID of the navigation operation.
+   */
   get navigationId() {
     return this._navigationId
   }
 }
 
+/**
+ * Represents a print result.
+ */
 class PrintResult {
   constructor(data) {
     this._data = data
   }
 
+  /**
+   * Gets the data associated with the print result.
+   * @returns {any} The data associated with the print result.
+   */
   get data() {
     return this._data
   }
@@ -472,18 +655,17 @@ class PrintResult {
  * @param driver
  * @param browsingContextId The browsing context of current window/tab
  * @param type "window" or "tab"
- * @param referenceContext To get a browsing context for this reference if passed
+ * @param createParameters The parameters for creating a new browsing context
  * @returns {Promise<BrowsingContext>}
  */
-async function getBrowsingContextInstance(driver, { browsingContextId, type, referenceContext }) {
+async function getBrowsingContextInstance(
+  driver,
+  { browsingContextId = undefined, type = undefined, createParameters = undefined },
+) {
   let instance = new BrowsingContext(driver)
-  await instance.init({ browsingContextId, type, referenceContext })
+  await instance.init({ browsingContextId, type, createParameters })
   return instance
 }
 
-/**
- * API
- * @type {function(*, {*,*,*}): Promise<BrowsingContext>}
- */
 module.exports = getBrowsingContextInstance
 module.exports.Locator = Locator

package/bidi/browsingContextInspector.js

@@ -17,6 +17,12 @@
 
 const { BrowsingContextInfo, NavigationInfo } = require('./browsingContextTypes')
 
+/**
+ * Represents a browsing context related events.
+ * Described in https://w3c.github.io/webdriver-bidi/#module-contexts-events.
+ * While BrowsingContext class represents a browsing context lifecycle and related commands.
+ * This class is specific to listening to events. Events can be subscribed to multiple browsing contexts or all of them.
+ */
 class BrowsingContextInspector {
   constructor(driver, browsingContextIds) {
     this._driver = driver
@@ -27,34 +33,79 @@ class BrowsingContextInspector {
     this.bidi = await this._driver.getBidi()
   }
 
+  /**
+   * Subscribes to the 'browsingContext.contextCreated' event.
+   * @param {Function} callback - The callback function to handle the event.
+   * @returns {Promise<void>} - A promise that resolves when the event is emitted.
+   */
   async onBrowsingContextCreated(callback) {
     await this.subscribeAndHandleEvent('browsingContext.contextCreated', callback)
   }
 
+  /**
+   * Subscribes to the 'browsingContext.contextDestroyed' event.
+   * @param {Function} callback - The callback function to handle the event.
+   * @returns {Promise<void>} - A promise that resolves when the event is emitted.
+   */
   async onBrowsingContextDestroyed(callback) {
     await this.subscribeAndHandleEvent('browsingContext.contextDestroyed', callback)
   }
 
+  /**
+   * Subscribe to the 'browsingContext.navigationStarted' event.
+   * @param {Function} callback - The callback function to handle the event.
+   * @returns {Promise<void>} - A promise that resolves when the event is emitted.
+   */
   async onNavigationStarted(callback) {
     await this.subscribeAndHandleEvent('browsingContext.navigationStarted', callback)
   }
 
+  /**
+   * Subscribes to the 'browsingContext.fragmentNavigated' event.
+   *
+   * @param {Function} callback - The callback function to handle the event.
+   * @returns {Promise<void>} - A promise that resolves when the event is emitted.
+   */
   async onFragmentNavigated(callback) {
     await this.subscribeAndHandleEvent('browsingContext.fragmentNavigated', callback)
   }
 
+  /**
+   * Subscribes to the 'browsingContext.userPromptClosed' event.
+   *
+   * @param {Function} callback - The callback function to handle the event.
+   * @returns {Promise<void>} - A promise that resolves when the event is emitted.
+   */
   async onUserPromptClosed(callback) {
     await this.subscribeAndHandleEvent('browsingContext.userPromptClosed', callback)
   }
 
+  /**
+   * Subscribes to the 'browsingContext.userPromptOpened' event.
+   *
+   * @param {Function} callback - The callback function to handle the event.
+   * @returns {Promise<void>} - A promise that resolves when the event is emitted.
+   */
   async onUserPromptOpened(callback) {
     await this.subscribeAndHandleEvent('browsingContext.userPromptOpened', callback)
   }
 
+  /**
+   * Subscribes to the 'browsingContext.domContentLoaded' event.
+   *
+   * @param {Function} callback - The callback function to handle the event.
+   * @returns {Promise<void>} - A promise that resolves when the event is emitted.
+   */
   async onDomContentLoaded(callback) {
     await this.subscribeAndHandleEvent('browsingContext.domContentLoaded', callback)
   }
 
+  /**
+   * Subscribes to the 'browsingContext.load' event.
+   *
+   * @param {Function} callback - The callback function to handle the event.
+   * @returns {Promise<void>} - A promise that resolves when the event is emitted.
+   */
   async onBrowsingContextLoaded(callback) {
     await this.subscribeAndHandleEvent('browsingContext.load', callback)
   }

package/bidi/browsingContextTypes.js

@@ -15,6 +15,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
+/**
+ * Represents information about a browsing context.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-browsingContext-Info
+ */
 class BrowsingContextInfo {
   constructor(id, url, children, parentBrowsingContext) {
     this._id = id
@@ -23,24 +27,51 @@ class BrowsingContextInfo {
     this._parentBrowsingContext = parentBrowsingContext
   }
 
+  /**
+   * Get the ID of the browsing context.
+   * @returns {string} The ID of the browsing context.
+   */
   get id() {
     return this._id
   }
 
+  /**
+   * Get the URL of the browsing context.
+   * @returns {string} The URL of the browsing context.
+   */
   get url() {
     return this._url
   }
 
+  /**
+   * Get the children of the browsing context.
+   * @returns {Array<BrowsingContextInfo>} The children of the browsing context.
+   */
   get children() {
     return this._children
   }
 
+  /**
+   * Get the parent browsing context.
+   * @returns {BrowsingContextInfo} The parent browsing context.
+   */
   get parentBrowsingContext() {
     return this._parentBrowsingContext
   }
 }
 
+/**
+ * Represents information about a navigation.
+ * Described in https://w3c.github.io/webdriver-bidi/#type-browsingContext-NavigationInfo.
+ */
 class NavigationInfo {
+  /**
+   * Constructs a new NavigationInfo object.
+   * @param {string} browsingContextId - The ID of the browsing context.
+   * @param {string} navigationId - The ID of the navigation.
+   * @param {number} timestamp - The timestamp of the navigation.
+   * @param {string} url - The URL of the page navigated to.
+   */
   constructor(browsingContextId, navigationId, timestamp, url) {
     this.browsingContextId = browsingContextId
     this.navigationId = navigationId