selenium-webdriver 4.16.0 → 4.17.0

package/CHANGES.md

@@ -1,3 +1,20 @@
+## 4.17.0
+
+* Add javascript to Selenium Manager input for tracking (see #13288)
+* remove deprecated headless methods and associated references
+* Add script message event (#13153)
+* Update channel name from Aurora to Dev
+* Remove firefox_channels.js example as Channels is deprecated
+* Add Input module command (#13360)
+* remove all references to firefox-bin
+* download files from remote server (#13102)
+* Add auth required event
+* Add traverse history command
+* Add test to get iframe's browsing context
+* Add Input module JS command
+* Add test for node properties in
+* Add CDP for Chrome 121 and remove 118
+
 ## 4.16.0
 
 #### :bug: Bug fix

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/browsingContext.js

@@ -186,7 +186,7 @@ class BrowsingContext {
       params: {
         context: this._id,
         clip: {
-          type: 'viewport',
+          type: 'box',
           x: x,
           y: y,
           width: width,
@@ -195,7 +195,10 @@ 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']
   }
@@ -309,6 +312,25 @@ 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)
+  }
 }
 
 class NavigateResult {

package/bidi/input.js

@@ -0,0 +1,100 @@
+// 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.
+
+// type: module added to package.json
+// import { WebElement } from '../lib/webdriver'
+const { WebElement } = require('../lib/webdriver')
+
+class Input {
+  constructor(driver) {
+    this._driver = driver
+  }
+
+  async init() {
+    if (!(await this._driver.getCapabilities()).get('webSocketUrl')) {
+      throw Error('WebDriver instance must support BiDi protocol')
+    }
+
+    this.bidi = await this._driver.getBidi()
+  }
+
+  async perform(browsingContextId, actions) {
+    const _actions = await updateActions(actions)
+
+    const command = {
+      method: 'input.performActions',
+      params: {
+        context: browsingContextId,
+        actions: _actions,
+      },
+    }
+
+    let response = await this.bidi.send(command)
+
+    return response
+  }
+
+  async release(browsingContextId) {
+    const command = {
+      method: 'input.releaseActions',
+      params: {
+        context: browsingContextId,
+      },
+    }
+    return await this.bidi.send(command)
+  }
+}
+
+async function updateActions(actions) {
+  const _actions = []
+  for (const action of actions) {
+    const sequenceList = action.actions
+    let updatedSequenceList = []
+
+    if (action.type === 'pointer' || action.type === 'wheel') {
+      for (const sequence of sequenceList) {
+        if (
+          (sequence.type === 'pointerMove' || sequence.type === 'scroll') &&
+          sequence.origin instanceof WebElement
+        ) {
+          const element = sequence.origin
+          const elementId = await element.getId()
+          sequence.origin = {
+            type: 'element',
+            element: { sharedId: elementId },
+          }
+        }
+        updatedSequenceList.push(sequence)
+      }
+
+      const updatedAction = { ...action, actions: updatedSequenceList }
+      _actions.push(updatedAction)
+    } else {
+      _actions.push(action)
+    }
+  }
+
+  return _actions
+}
+
+async function getInputInstance(driver) {
+  let instance = new Input(driver)
+  await instance.init()
+  return instance
+}
+
+module.exports = getInputInstance

package/bidi/networkInspector.js

@@ -39,6 +39,10 @@ class NetworkInspector {
     await this.subscribeAndHandleEvent('network.responseCompleted', callback)
   }
 
+  async authRequired(callback) {
+    await this.subscribeAndHandleEvent('network.authRequired', callback)
+  }
+
   async subscribeAndHandleEvent(eventType, callback) {
     if (this._browsingContextIds != null) {
       await this.bidi.subscribe(eventType, this._browsingContextIds)

package/bidi/protocolType.js

@@ -42,6 +42,7 @@ const NonPrimitiveType = {
   OBJECT: 'object',
   REGULAR_EXPRESSION: 'regexp',
   SET: 'set',
+  CHANNEL: 'channel',
 
   findByName(name) {
     return (

package/bidi/protocolValue.js

@@ -25,7 +25,7 @@ const TYPE_CONSTANT = 'type'
 const VALUE_CONSTANT = 'value'
 const RemoteReferenceType = {
   HANDLE: 'handle',
-  SHARED_ID: 'shareId',
+  SHARED_ID: 'sharedId',
 }
 
 class LocalValue {
@@ -98,6 +98,10 @@ class LocalValue {
     return new LocalValue(NonPrimitiveType.SET, value)
   }
 
+  static createChannelValue(value) {
+    return new LocalValue(NonPrimitiveType.CHANNEL, value)
+  }
+
   toJson() {
     let toReturn = {}
     toReturn[TYPE_CONSTANT] = this.type
@@ -165,12 +169,12 @@ class RemoteValue {
 }
 
 class ReferenceValue {
-  constructor(handle, shareId) {
+  constructor(handle, sharedId) {
     if (handle === RemoteReferenceType.HANDLE) {
-      this.handle = shareId
+      this.handle = sharedId
     } else {
       this.handle = handle
-      this.shareId = shareId
+      this.sharedId = sharedId
     }
   }
 
@@ -180,8 +184,8 @@ class ReferenceValue {
       toReturn[RemoteReferenceType.HANDLE] = this.handle
     }
 
-    if (this.shareId != null) {
-      toReturn[RemoteReferenceType.SHARED_ID] = this.shareId
+    if (this.sharedId != null) {
+      toReturn[RemoteReferenceType.SHARED_ID] = this.sharedId
     }
 
     return toReturn
@@ -195,10 +199,56 @@ class RegExpValue {
   }
 }
 
+class SerializationOptions {
+  constructor(
+    maxDomDepth = 0,
+    maxObjectDepth = null,
+    includeShadowTree = 'none'
+  ) {
+    this._maxDomDepth = maxDomDepth
+    this._maxObjectDepth = maxObjectDepth
+
+    if (['none', 'open', 'all'].includes(includeShadowTree)) {
+      throw Error(
+        `Valid types are 'none', 'open', and 'all'. Received: ${includeShadowTree}`
+      )
+    }
+    this._includeShadowTree = includeShadowTree
+  }
+}
+
+class ChannelValue {
+  constructor(channel, options = undefined, resultOwnership = undefined) {
+    this.channel = channel
+
+    if (options !== undefined) {
+      if (options instanceof SerializationOptions) {
+        this.options = options
+      } else {
+        throw Error(
+          `Pass in SerializationOptions object. Received: ${options} `
+        )
+      }
+    }
+
+    if (resultOwnership != undefined) {
+      if (['root', 'none'].includes(resultOwnership)) {
+        this.resultOwnership = resultOwnership
+      } else {
+        throw Error(
+          `Valid types are 'root' and 'none. Received: ${resultOwnership}`
+        )
+      }
+    }
+  }
+}
+
 module.exports = {
+  ChannelValue,
   LocalValue,
   RemoteValue,
   ReferenceValue,
   RemoteReferenceType,
   RegExpValue,
+  SerializationOptions,
 }

package/bidi/realmInfo.js

@@ -96,4 +96,5 @@ class WindowRealmInfo extends RealmInfo {
 module.exports = {
   RealmInfo,
   RealmType,
+  WindowRealmInfo,
 }

package/bidi/scriptManager.js

@@ -21,8 +21,10 @@ const {
   EvaluateResultException,
   ExceptionDetails,
 } = require('./evaluateResult')
-const { RealmInfo } = require('./realmInfo')
+const { Message } = require('./scriptTypes')
+const { RealmInfo, RealmType, WindowRealmInfo } = require('./realmInfo')
 const { RemoteValue } = require('./protocolValue')
+const { Source } = require('./scriptTypes')
 const { WebDriverError } = require('../lib/error')
 
 class ScriptManager {
@@ -348,6 +350,55 @@ class ScriptManager {
     let response = await this.bidi.send(command)
     return this.realmInfoMapper(response.result.realms)
   }
+
+  async onMessage(callback) {
+    await this.subscribeAndHandleEvent('script.message', callback)
+  }
+
+  async onRealmCreated(callback) {
+    await this.subscribeAndHandleEvent('script.realmCreated', callback)
+  }
+
+  async subscribeAndHandleEvent(eventType, callback) {
+    if (this._browsingContextIds != null) {
+      await this.bidi.subscribe(eventType, this._browsingContextIds)
+    } else {
+      await this.bidi.subscribe(eventType)
+    }
+    await this._on(callback)
+  }
+
+  async _on(callback) {
+    this.ws = await this.bidi.socket
+    this.ws.on('message', (event) => {
+      const { params } = JSON.parse(Buffer.from(event.toString()))
+      if (params) {
+        let response = null
+        if ('channel' in params) {
+          response = new Message(
+            params.channel,
+            new RemoteValue(params.data),
+            new Source(params.source)
+          )
+        } else if ('realm' in params) {
+          if (params.type === RealmType.WINDOW) {
+            response = new WindowRealmInfo(
+              params.realm,
+              params.origin,
+              params.type,
+              params.context,
+              params.sandbox
+            )
+          } else if (params.realm !== null && params.type !== null) {
+            response = new RealmInfo(params.realm, params.origin, params.type)
+          } else if (params.realm !== null) {
+            response = params.realm
+          }
+        }
+        callback(response)
+      }
+    })
+  }
 }
 
 async function getScriptManagerInstance(browsingContextId, driver) {

package/bidi/scriptTypes.js

@@ -0,0 +1,58 @@
+// 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.
+
+class Message {
+  constructor(channel, data, source) {
+    this._channel = channel
+    this._data = data
+    this._source = source
+  }
+
+  get channel() {
+    return this._channel
+  }
+
+  get data() {
+    return this._data
+  }
+
+  get source() {
+    return this._source
+  }
+}
+
+class Source {
+  constructor(source) {
+    this._browsingContextId = null
+    this._realmId = source.realm
+
+    // Browsing context is returned as an optional parameter
+    if ('context' in source) {
+      this._browsingContextId = source.context
+    }
+  }
+
+  get browsingContextId() {
+    return this._browsingContextId
+  }
+
+  get realmId() {
+    return this._realmId
+  }
+}
+
+module.exports = { Message, Source }

package/chrome.js

@@ -36,17 +36,12 @@
  *     a unique browser session with a clean user profile (unless otherwise
  *     configured through the {@link Options} class).
  *
- * __Headless Chrome__ <a id="headless"></a>
- *
- * To start Chrome in headless mode, simply call
- * {@linkplain Options#headless Options.headless()}.
- *
  *     let chrome = require('selenium-webdriver/chrome');
  *     let {Builder} = require('selenium-webdriver');
  *
  *     let driver = new Builder()
  *         .forBrowser('chrome')
- *         .setChromeOptions(new chrome.Options().headless())
+ *         .setChromeOptions(new chrome.Options())
  *         .build();
  *
  * __Customizing the ChromeDriver Server__ <a id="custom-server"></a>

package/chromium.js

@@ -36,17 +36,12 @@
  *     a unique browser session with a clean user profile (unless otherwise
  *     configured through the {@link Options} class).
  *
- * __Headless Chromium__ <a id="headless"></a>
- *
- * To start the browser in headless mode, simply call
- * {@linkplain Options#headless Options.headless()}.
- *
  *     let chrome = require('selenium-webdriver/chrome');
  *     let {Builder} = require('selenium-webdriver');
  *
  *     let driver = new Builder()
  *         .forBrowser('chrome')
- *         .setChromeOptions(new chrome.Options().headless())
+ *         .setChromeOptions(new chrome.Options())
  *         .build();
  *
  * __Customizing the Chromium WebDriver Server__ <a id="custom-server"></a>
@@ -310,34 +305,6 @@ class Options extends Capabilities {
     return this
   }
 
-  /**
-   * @deprecated Use {@link Options#addArguments} instead.
-   * @example
-   * options.addArguments('--headless=chrome'); (or)
-   * options.addArguments('--headless');
-   * @example
-   *
-   * Recommended to use '--headless=chrome' as argument for browsers v94-108.
-   * Recommended to use '--headless=new' as argument for browsers v109+.
-   *
-   * Configures the driver to start the browser in headless mode.
-   *
-   * > __NOTE:__ Resizing the browser window in headless mode is only supported
-   * > in Chromium 60+. Users are encouraged to set an initial window size with
-   * > the {@link #windowSize windowSize({width, height})} option.
-   *
-   * > __NOTE__: For security, Chromium disables downloads by default when
-   * > in headless mode (to prevent sites from silently downloading files to
-   * > your machine). After creating a session, you may call
-   * > {@link ./chrome.Driver#setDownloadPath setDownloadPath} to re-enable
-   * > downloads, saving files in the specified directory.
-   *
-   * @return {!Options} A self reference.
-   */
-  headless() {
-    return this.addArguments('headless')
-  }
-
   /**
    * Sets the initial window size.
    *

package/common/seleniumManager.js

@@ -35,7 +35,7 @@ let debugMessagePrinted = false
  * Determines the path of the correct Selenium Manager binary
  * @returns {string}
  */
-function getBinary() {
+function getBinary () {
   const directory = {
     darwin: 'macos',
     win32: 'windows',
@@ -48,7 +48,8 @@ function getBinary() {
 
   let seleniumManagerBasePath = path.join(__dirname, '..', '/bin')
 
-  const filePath = process.env.SE_MANAGER_PATH || path.join(seleniumManagerBasePath, directory, file)
+  const filePath = process.env.SE_MANAGER_PATH || path.join(
+    seleniumManagerBasePath, directory, file)
 
   if (!fs.existsSync(filePath)) {
     throw new Error(`Unable to obtain Selenium Manager at ${filePath}`)
@@ -69,8 +70,9 @@ function getBinary() {
  * browser location
  */
 
-function driverLocation(options) {
-  let args = ['--browser', options.getBrowserName(), '--output', 'json']
+function driverLocation (options) {
+  let args = ['--browser', options.getBrowserName(), '--language-binding',
+    'javascript', '--output', 'json']
 
   if (options.getBrowserVersion() && options.getBrowserVersion() !== '') {
     args.push('--browser-version', options.getBrowserVersion())
@@ -139,7 +141,7 @@ function driverLocation(options) {
   }
 }
 
-function logOutput(output) {
+function logOutput (output) {
   for (const key in output.logs) {
     if (output.logs[key].level === 'WARN') {
       log_.warning(`${output.logs[key].message}`)

package/example/headless.js

@@ -41,10 +41,10 @@ const height = 480
 let driver = new Builder()
   .forBrowser('chrome')
   .setChromeOptions(
-    new chrome.Options().headless().windowSize({ width, height })
+    new chrome.Options().addArguments('-headless').windowSize({ width, height })
   )
   .setFirefoxOptions(
-    new firefox.Options().headless().windowSize({ width, height })
+    new firefox.Options().addArguments('-headless').windowSize({ width, height })
   )
   .build()