selenium-webdriver 4.16.0 → 4.18.0

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2023 Software Freedom Conservancy (SFC)
+   Copyright 2024 Software Freedom Conservancy (SFC)
 
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.

package/NOTICE

@@ -1,2 +1,2 @@
-Copyright 2011-2023 Software Freedom Conservancy
+Copyright 2011-2024 Software Freedom Conservancy
 Copyright 2004-2011 Selenium committers

package/bidi/addInterceptParameters.js

@@ -0,0 +1,86 @@
+// 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.
+
+const {UrlPattern} = require("./urlPattern");
+
+class AddInterceptParameters {
+  #phases = []
+  #urlPatterns = []
+
+  constructor(phases) {
+    if (phases instanceof Array) {
+      phases.forEach(phase => this.#phases.push(phase))
+    } else {
+      this.#phases.push(phases)
+    }
+  }
+
+    urlPattern(pattern)
+    {
+      if (!pattern instanceof UrlPattern) {
+        throw new Error(`Pattern must be an instance of UrlPattern. Received: '${pattern})'`)
+      }
+      this.#urlPatterns.push(Object.fromEntries(pattern.asMap()))
+      return this
+    }
+
+    urlPatterns(patterns)
+    {
+      patterns.forEach(pattern => {
+        if (!pattern instanceof UrlPattern) {
+          throw new Error(`Pattern must be an instance of UrlPattern. Received:'${pattern}'`)
+        }
+        this.#urlPatterns.push(Object.fromEntries(pattern.asMap()))
+      })
+      return this
+    }
+
+    urlStringPattern(pattern)
+    {
+      if (!pattern instanceof String) {
+        throw new Error(`Pattern must be an instance of String. Received:'${pattern}'`)
+      }
+
+      this.#urlPatterns.push({'type': 'string', 'pattern': pattern})
+      return this
+    }
+
+    urlStringPatterns(patterns)
+    {
+      patterns.forEach(pattern => {
+        if (!pattern instanceof String) {
+          throw new Error(`Pattern must be an instance of String. Received:'${pattern}'`)
+        }
+        this.#urlPatterns.push({'type': 'string', 'pattern': pattern})
+      })
+      return this
+    }
+
+
+    asMap()
+    {
+      const map = new Map()
+      map.set('phases', this.#phases)
+      if (this.#urlPatterns.length > 0) {
+        map.set('urlPatterns', this.#urlPatterns)
+      }
+
+      return map
+    }
+  }
+
+  module.exports = {AddInterceptParameters}

package/bidi/browsingContext.js

@@ -17,6 +17,55 @@
 
 const { InvalidArgumentError, NoSuchFrameError } = require('../lib/error')
 const { BrowsingContextInfo } = require('./browsingContextTypes')
+const { SerializationOptions, ReferenceValue, RemoteValue } = require('./protocolValue')
+const { WebElement } = require('../lib/webdriver')
+
+class Locator {
+  static Type = Object.freeze({
+    CSS: 'css',
+    INNER_TEXT: 'innerText',
+    XPATH: 'xpath',
+  })
+
+  #type
+  #value
+  #ignoreCase
+  #matchType
+  #maxDepth
+
+  constructor(type, value, ignoreCase = undefined, matchType = undefined, maxDepth = undefined) {
+    this.#type = type
+    this.#value = value
+    this.#ignoreCase = ignoreCase
+    this.#matchType = matchType
+    this.#maxDepth = maxDepth
+  }
+
+  static css(value) {
+    return new Locator(Locator.Type.CSS, value)
+  }
+
+  static xpath(value) {
+    return new Locator(Locator.Type.XPATH, value)
+  }
+
+  static innerText(value, ignoreCase = undefined, matchType = undefined, maxDepth = undefined) {
+    return new Locator(Locator.Type.INNER_TEXT, value, ignoreCase, matchType, maxDepth)
+  }
+
+  toMap() {
+    const map = new Map()
+
+    map.set('type', this.#type.toString())
+    map.set('value', this.#value)
+    map.set('ignoreCase', this.#ignoreCase)
+    map.set('matchType', this.#matchType)
+    map.set('maxDepth', this.#maxDepth)
+
+    return map
+  }
+}
+
 class BrowsingContext {
   constructor(driver) {
     this._driver = driver
@@ -65,13 +114,8 @@ class BrowsingContext {
    * @returns NavigateResult object
    */
   async navigate(url, readinessState = undefined) {
-    if (
-      readinessState !== undefined &&
-      !['none', 'interactive', 'complete'].includes(readinessState)
-    ) {
-      throw Error(
-        `Valid readiness states are 'none', 'interactive' & 'complete'. Received: ${readinessState}`
-      )
+    if (readinessState !== undefined && !['none', 'interactive', 'complete'].includes(readinessState)) {
+      throw Error(`Valid readiness states are 'none', 'interactive' & 'complete'. Received: ${readinessState}`)
     }
 
     const params = {
@@ -84,10 +128,7 @@ class BrowsingContext {
     }
     const navigateResult = (await this.bidi.send(params))['result']
 
-    return new NavigateResult(
-      navigateResult['url'],
-      navigateResult['navigation']
-    )
+    return new NavigateResult(navigateResult['url'], navigateResult['navigation'])
   }
 
   /**
@@ -109,12 +150,7 @@ class BrowsingContext {
     }
 
     result = result['result']['contexts'][0]
-    return new BrowsingContextInfo(
-      result['context'],
-      result['url'],
-      result['children'],
-      result['parent']
-    )
+    return new BrowsingContextInfo(result['context'], result['url'], result['children'], result['parent'])
   }
 
   /**
@@ -186,7 +222,7 @@ class BrowsingContext {
       params: {
         context: this._id,
         clip: {
-          type: 'viewport',
+          type: 'box',
           x: x,
           y: y,
           width: width,
@@ -195,16 +231,15 @@ 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
-  ) {
+  async captureElementScreenshot(sharedId, handle = undefined, scrollIntoView = undefined) {
     let params = {
       method: 'browsingContext.captureScreenshot',
       params: {
@@ -270,13 +305,8 @@ class BrowsingContext {
   }
 
   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}`
-      )
+    if (readinessState !== undefined && !['none', 'interactive', 'complete'].includes(readinessState)) {
+      throw Error(`Valid readiness states are 'none', 'interactive' & 'complete'. Received: ${readinessState}`)
     }
 
     const params = {
@@ -289,10 +319,7 @@ class BrowsingContext {
     }
     const navigateResult = (await this.bidi.send(params))['result']
 
-    return new NavigateResult(
-      navigateResult['url'],
-      navigateResult['navigation']
-    )
+    return new NavigateResult(navigateResult['url'], navigateResult['navigation'])
   }
 
   async setViewport(width, height, devicePixelRatio = undefined) {
@@ -309,6 +336,110 @@ class BrowsingContext {
       throw Error(result['error'])
     }
   }
+
+  async traverseHistory(delta) {
+    const params = {
+      method: 'browsingContext.traverseHistory',
+      params: {
+        context: this._id,
+        delta: delta,
+      },
+    }
+    await this.bidi.send(params)
+  }
+
+  async forward() {
+    await this.traverseHistory(1)
+  }
+
+  async back() {
+    await this.traverseHistory(-1)
+  }
+
+  async locateNodes(
+    locator,
+    maxNodeCount = undefined,
+    ownership = undefined,
+    sandbox = undefined,
+    serializationOptions = undefined,
+    startNodes = undefined,
+  ) {
+    if (!(locator instanceof Locator)) {
+      throw Error(`Pass in a Locator object. Received: ${locator}`)
+    }
+
+    if (serializationOptions !== undefined && !(serializationOptions instanceof SerializationOptions)) {
+      throw Error(`Pass in SerializationOptions object. Received: ${serializationOptions} `)
+    }
+
+    if (ownership !== undefined && !['root', 'none'].includes(ownership)) {
+      throw Error(`Valid types are 'root' and 'none. Received: ${ownership}`)
+    }
+
+    if (startNodes !== undefined && !Array.isArray(startNodes)) {
+      throw Error(`Pass in an array of ReferenceValue objects. Received: ${startNodes}`)
+    }
+
+    if (startNodes !== undefined && Array.isArray(startNodes)) {
+      startNodes.forEach((node) => {
+        if (!(node instanceof ReferenceValue)) {
+          throw Error(`Pass in a ReferenceValue object. Received: ${node}`)
+        }
+      })
+    }
+
+    const params = {
+      method: 'browsingContext.locateNodes',
+      params: {
+        context: this._id,
+        locator: Object.fromEntries(locator.toMap()),
+        maxNodeCount: maxNodeCount,
+        ownership: ownership,
+        sandbox: sandbox,
+        serializationOptions: serializationOptions,
+        startNodes: startNodes,
+      },
+    }
+
+    let response = await this.bidi.send(params)
+    if ('error' in response) {
+      throw Error(response['error'])
+    }
+
+    const nodes = response.result.nodes
+    const remoteValues = []
+
+    nodes.forEach((node) => {
+      remoteValues.push(new RemoteValue(node))
+    })
+    return remoteValues
+  }
+
+  async locateNode(
+    locator,
+    ownership = undefined,
+    sandbox = undefined,
+    serializationOptions = undefined,
+    startNodes = undefined,
+  ) {
+    const elements = await this.locateNodes(locator, 1, ownership, sandbox, serializationOptions, startNodes)
+    return elements[0]
+  }
+
+  async locateElement(locator) {
+    const elements = await this.locateNodes(locator, 1)
+    return new WebElement(this._driver, elements[0].sharedId)
+  }
+
+  async locateElements(locator) {
+    const elements = await this.locateNodes(locator)
+
+    let webElements = []
+    elements.forEach((element) => {
+      webElements.push(new WebElement(this._driver, element.sharedId))
+    })
+    return webElements
+  }
 }
 
 class NavigateResult {
@@ -344,10 +475,7 @@ class PrintResult {
  * @param referenceContext To get a browsing context for this reference if passed
  * @returns {Promise<BrowsingContext>}
  */
-async function getBrowsingContextInstance(
-  driver,
-  { browsingContextId, type, referenceContext }
-) {
+async function getBrowsingContextInstance(driver, { browsingContextId, type, referenceContext }) {
   let instance = new BrowsingContext(driver)
   await instance.init({ browsingContextId, type, referenceContext })
   return instance
@@ -358,3 +486,4 @@ async function getBrowsingContextInstance(
  * @type {function(*, {*,*,*}): Promise<BrowsingContext>}
  */
 module.exports = getBrowsingContextInstance
+module.exports.Locator = Locator

package/bidi/browsingContextInspector.js

@@ -15,10 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-const {
-  BrowsingContextInfo,
-  NavigationInfo,
-} = require('./browsingContextTypes')
+const { BrowsingContextInfo, NavigationInfo } = require('./browsingContextTypes')
 
 class BrowsingContextInspector {
   constructor(driver, browsingContextIds) {
@@ -31,45 +28,31 @@ class BrowsingContextInspector {
   }
 
   async onBrowsingContextCreated(callback) {
-    await this.subscribeAndHandleEvent(
-      'browsingContext.contextCreated',
-      callback
-    )
+    await this.subscribeAndHandleEvent('browsingContext.contextCreated', callback)
+  }
+
+  async onBrowsingContextDestroyed(callback) {
+    await this.subscribeAndHandleEvent('browsingContext.contextDestroyed', callback)
   }
 
   async onNavigationStarted(callback) {
-    await this.subscribeAndHandleEvent(
-      'browsingContext.navigationStarted',
-      callback
-    )
+    await this.subscribeAndHandleEvent('browsingContext.navigationStarted', callback)
   }
 
   async onFragmentNavigated(callback) {
-    await this.subscribeAndHandleEvent(
-      'browsingContext.fragmentNavigated',
-      callback
-    )
+    await this.subscribeAndHandleEvent('browsingContext.fragmentNavigated', callback)
   }
 
   async onUserPromptClosed(callback) {
-    await this.subscribeAndHandleEvent(
-      'browsingContext.userPromptClosed',
-      callback
-    )
+    await this.subscribeAndHandleEvent('browsingContext.userPromptClosed', callback)
   }
 
   async onUserPromptOpened(callback) {
-    await this.subscribeAndHandleEvent(
-      'browsingContext.userPromptOpened',
-      callback
-    )
+    await this.subscribeAndHandleEvent('browsingContext.userPromptOpened', callback)
   }
 
   async onDomContentLoaded(callback) {
-    await this.subscribeAndHandleEvent(
-      'browsingContext.domContentLoaded',
-      callback
-    )
+    await this.subscribeAndHandleEvent('browsingContext.domContentLoaded', callback)
   }
 
   async onBrowsingContextLoaded(callback) {
@@ -92,21 +75,11 @@ class BrowsingContextInspector {
       if (params) {
         let response = null
         if ('navigation' in params) {
-          response = new NavigationInfo(
-            params.context,
-            params.navigation,
-            params.timestamp,
-            params.url
-          )
+          response = new NavigationInfo(params.context, params.navigation, params.timestamp, params.url)
         } else if ('accepted' in params) {
           /* Needs to be updated when browsers implement other events */
         } else {
-          response = new BrowsingContextInfo(
-            params.context,
-            params.url,
-            params.children,
-            params.parent
-          )
+          response = new BrowsingContextInfo(params.context, params.url, params.children, params.parent)
         }
         callback(response)
       }

package/bidi/evaluateResult.js

@@ -38,16 +38,10 @@ class EvaluateResultException {
 
 class ExceptionDetails {
   constructor(exceptionDetails) {
-    this.columnNumber =
-      'columnNumber' in exceptionDetails
-        ? exceptionDetails['columnNumber']
-        : null
-    this.exception =
-      'exception' in exceptionDetails ? exceptionDetails['exception'] : null
-    this.lineNumber =
-      'lineNumber' in exceptionDetails ? exceptionDetails['lineNumber'] : null
-    this.stackTrace =
-      'stackTrace' in exceptionDetails ? exceptionDetails['stackTrace'] : null
+    this.columnNumber = 'columnNumber' in exceptionDetails ? exceptionDetails['columnNumber'] : null
+    this.exception = 'exception' in exceptionDetails ? exceptionDetails['exception'] : null
+    this.lineNumber = 'lineNumber' in exceptionDetails ? exceptionDetails['lineNumber'] : null
+    this.stackTrace = 'stackTrace' in exceptionDetails ? exceptionDetails['stackTrace'] : null
     this.text = 'text' in exceptionDetails ? exceptionDetails['text'] : null
   }
 }

package/bidi/filterBy.js

@@ -21,13 +21,9 @@ class FilterBy {
   }
 
   static logLevel(level) {
-    if (
-      level === undefined ||
-      (level != undefined &&
-        !['debug', 'error', 'info', 'warning'].includes(level))
-    ) {
+    if (level === undefined || (level != undefined && !['debug', 'error', 'info', 'warning'].includes(level))) {
       throw Error(
-        `Please pass valid log level. Valid log levels are 'debug', 'error', 'info' and 'warning'. Received: ${level}`
+        `Please pass valid log level. Valid log levels are 'debug', 'error', 'info' and 'warning'. Received: ${level}`,
       )
     }
 

package/bidi/index.js

@@ -15,6 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
+// eslint-disable-next-line node/no-missing-require
 const { EventEmitter } = require('node:events')
 const WebSocket = require('ws')
 
@@ -22,7 +23,7 @@ const RESPONSE_TIMEOUT = 1000 * 30
 
 class Index extends EventEmitter {
   id = 0
-  isConnected = false
+  connected = false
   events = []
   browsingContexts = []
 
@@ -30,12 +31,12 @@ class Index extends EventEmitter {
    * Create a new websocket connection
    * @param _webSocketUrl
    */
-  constructor (_webSocketUrl) {
+  constructor(_webSocketUrl) {
     super()
-    this.isConnected = false
+    this.connected = false
     this._ws = new WebSocket(_webSocketUrl)
     this._ws.on('open', () => {
-      this.isConnected = true
+      this.connected = true
     })
   }
 
@@ -43,9 +44,9 @@ class Index extends EventEmitter {
    * Resolve connection
    * @returns {Promise<unknown>}
    */
-  async waitForConnection () {
+  async waitForConnection() {
     return new Promise((resolve) => {
-      if (this.isConnected) {
+      if (this.connected) {
         resolve()
       } else {
         this._ws.once('open', () => {
@@ -58,15 +59,15 @@ class Index extends EventEmitter {
   /**
    * @returns {WebSocket}
    */
-  get socket () {
+  get socket() {
     return this._ws
   }
 
   /**
    * @returns {boolean|*}
    */
-  get isConnected () {
-    return this.isConnected
+  get isConnected() {
+    return this.connected
   }
 
   /**
@@ -74,8 +75,8 @@ class Index extends EventEmitter {
    * @param params
    * @returns {Promise<unknown>}
    */
-  async send (params) {
-    if (!this.isConnected) {
+  async send(params) {
+    if (!this.connected) {
       await this.waitForConnection()
     }
 
@@ -98,6 +99,7 @@ class Index extends EventEmitter {
             resolve(payload)
           }
         } catch (err) {
+          // eslint-disable-next-line no-undef
           log.error(`Failed parse message: ${err.message}`)
         }
       }
@@ -112,8 +114,8 @@ class Index extends EventEmitter {
    * @param browsingContexts
    * @returns {Promise<void>}
    */
-  async subscribe (events, browsingContexts) {
-    function toArray (arg) {
+  async subscribe(events, browsingContexts) {
+    function toArray(arg) {
       if (arg === undefined) {
         return []
       }
@@ -125,16 +127,15 @@ class Index extends EventEmitter {
     const contextsArray = toArray(browsingContexts)
 
     const params = {
-      method: 'session.subscribe', params: {},
+      method: 'session.subscribe',
+      params: {},
     }
 
-    if (eventsArray.length && eventsArray.some(
-      event => typeof event !== 'string')) {
+    if (eventsArray.length && eventsArray.some((event) => typeof event !== 'string')) {
       throw new TypeError('events should be string or string array')
     }
 
-    if (contextsArray.length && contextsArray.some(
-      context => typeof context !== 'string')) {
+    if (contextsArray.length && contextsArray.some((context) => typeof context !== 'string')) {
       throw new TypeError('browsingContexts should be string or string array')
     }
 
@@ -155,24 +156,24 @@ class Index extends EventEmitter {
    * @param browsingContexts
    * @returns {Promise<void>}
    */
-  async unsubscribe (events, browsingContexts) {
+  async unsubscribe(events, browsingContexts) {
     if (typeof events === 'string') {
-      this.events = this.events.filter(event => event !== events)
+      this.events = this.events.filter((event) => event !== events)
     } else if (Array.isArray(events)) {
-      this.events = this.events.filter(event => !events.includes(event))
+      this.events = this.events.filter((event) => !events.includes(event))
     }
 
     if (typeof browsingContexts === 'string') {
       this.browsingContexts.pop()
     } else if (Array.isArray(browsingContexts)) {
-      this.browsingContexts =
-        this.browsingContexts.filter(id => !browsingContexts.includes(id))
+      this.browsingContexts = this.browsingContexts.filter((id) => !browsingContexts.includes(id))
     }
 
     const params = {
-      method: 'session.unsubscribe', params: {
+      method: 'session.unsubscribe',
+      params: {
         events: this.events,
-      }
+      },
     }
 
     if (this.browsingContexts.length > 0) {
@@ -186,9 +187,10 @@ class Index extends EventEmitter {
    * Get Bidi Status
    * @returns {Promise<*>}
    */
-  get status () {
+  get status() {
     return this.send({
-      method: 'session.status', params: {}
+      method: 'session.status',
+      params: {},
     })
   }
 
@@ -196,7 +198,7 @@ class Index extends EventEmitter {
    * Close ws connection.
    * @returns {Promise<unknown>}
    */
-  close () {
+  close() {
     const closeWebSocket = (callback) => {
       // don't close if it's already closed
       if (this._ws.readyState === 3) {
@@ -211,7 +213,7 @@ class Index extends EventEmitter {
         this._ws.close()
       }
     }
-    return new Promise((fulfill, reject) => {
+    return new Promise((fulfill, _) => {
       closeWebSocket(fulfill)
     })
   }