selenium-webdriver 4.8.2 → 4.9.1

package/bidi/realmInfo.js

@@ -0,0 +1,99 @@
+// 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 RealmType = {
+  AUDIO_WORKLET: 'audio-worklet',
+  DEDICATED_WORKER: 'dedicated-worker',
+  PAINT_WORKLET: 'paint-worklet',
+  SERVICE_WORKED: 'service-worker',
+  SHARED_WORKED: 'shared-worker',
+  WINDOW: 'window',
+  WORKER: 'worker',
+  WORKLET: 'worklet',
+
+  findByName(name) {
+    return (
+      Object.values(this).find((type) => {
+        return (
+          typeof type === 'string' && name.toLowerCase() === type.toLowerCase()
+        )
+      }) || null
+    )
+  },
+}
+
+class RealmInfo {
+  constructor(realmId, origin, realmType) {
+    this.realmId = realmId
+    this.origin = origin
+    this.realmType = realmType
+  }
+
+  static fromJson(input) {
+    let realmId = null
+    let origin = null
+    let realmType = null
+    let browsingContext = null
+    let sandbox = null
+
+    if ('type' in input) {
+      let typeString = input['type']
+      realmType = RealmType.findByName(typeString)
+    }
+
+    if ('realm' in input) {
+      realmId = input['realm']
+    }
+
+    if ('origin' in input) {
+      origin = input['origin']
+    }
+
+    if ('context' in input) {
+      browsingContext = input['context']
+    }
+
+    if ('sandbox' in input) {
+      sandbox = input['sandbox']
+    }
+
+    if (realmType === RealmType.WINDOW) {
+      return new WindowRealmInfo(
+        realmId,
+        origin,
+        realmType,
+        browsingContext,
+        sandbox
+      )
+    }
+
+    return new RealmInfo(realmId, origin, realmType)
+  }
+}
+
+class WindowRealmInfo extends RealmInfo {
+  constructor(realmId, origin, realmType, browsingContext, sandbox = null) {
+    super(realmId, origin, realmType)
+    this.browsingContext = browsingContext
+    this.sandbox = sandbox
+  }
+}
+
+module.exports = {
+  RealmInfo,
+  RealmType,
+}

package/bidi/resultOwnership.js

@@ -0,0 +1,23 @@
+// 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 ResultOwnership = {
+  ROOT: 'root',
+  NONE: 'none',
+}
+
+module.exports = { ResultOwnership }

package/bidi/scriptManager.js

@@ -0,0 +1,325 @@
+// 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 {
+  EvaluateResultType,
+  EvaluateResultSuccess,
+  EvaluateResultException,
+  ExceptionDetails,
+} = require('./evaluateResult')
+const { RealmInfo } = require('./realmInfo')
+const { RemoteValue } = require('./protocolValue')
+
+class ScriptManager {
+  constructor(driver) {
+    this._driver = driver
+  }
+
+  async init(browsingContextId) {
+    if (!(await this._driver.getCapabilities()).get('webSocketUrl')) {
+      throw Error('WebDriver instance must support BiDi protocol')
+    }
+
+    this.bidi = await this._driver.getBidi()
+    this._browsingContextId = browsingContextId
+  }
+
+  async disownRealmScript(realmId, handles) {
+    const params = {
+      method: 'script.disown',
+      params: {
+        handles: handles,
+        target: {
+          realm: realmId,
+        },
+      },
+    }
+
+    await this.bidi.send(params)
+  }
+
+  async disownBrowsingContextScript(
+    browsingContextId,
+    handles,
+    sandbox = null
+  ) {
+    const params = {
+      method: 'script.disown',
+      params: {
+        handles: handles,
+        target: {
+          context: browsingContextId,
+        },
+      },
+    }
+
+    if (sandbox != null) {
+      params.params.target['sandbox'] = sandbox
+    }
+
+    await this.bidi.send(params)
+  }
+
+  async callFunctionInRealm(
+    realmId,
+    functionDeclaration,
+    awaitPromise,
+    argumentValueList = null,
+    thisParameter = null,
+    resultOwnership = null
+  ) {
+    const params = this.getCallFunctionParams(
+      'realm',
+      realmId,
+      null,
+      functionDeclaration,
+      awaitPromise,
+      argumentValueList,
+      thisParameter,
+      resultOwnership
+    )
+
+    const command = {
+      method: 'script.callFunction',
+      params,
+    }
+
+    let response = await this.bidi.send(command)
+    return this.createEvaluateResult(response)
+  }
+
+  async callFunctionInBrowsingContext(
+    browsingContextId,
+    functionDeclaration,
+    awaitPromise,
+    argumentValueList = null,
+    thisParameter = null,
+    resultOwnership = null,
+    sandbox = null
+  ) {
+    const params = this.getCallFunctionParams(
+      'contextTarget',
+      browsingContextId,
+      sandbox,
+      functionDeclaration,
+      awaitPromise,
+      argumentValueList,
+      thisParameter,
+      resultOwnership
+    )
+
+    const command = {
+      method: 'script.callFunction',
+      params,
+    }
+    const response = await this.bidi.send(command)
+    return this.createEvaluateResult(response)
+  }
+
+  async evaluateFunctionInRealm(
+    realmId,
+    expression,
+    awaitPromise,
+    resultOwnership = null
+  ) {
+    const params = this.getEvaluateParams(
+      'realm',
+      realmId,
+      null,
+      expression,
+      awaitPromise,
+      resultOwnership
+    )
+
+    const command = {
+      method: 'script.evaluate',
+      params,
+    }
+
+    let response = await this.bidi.send(command)
+    return this.createEvaluateResult(response)
+  }
+
+  async evaluateFunctionInBrowsingContext(
+    browsingContextId,
+    expression,
+    awaitPromise,
+    resultOwnership = null,
+    sandbox = null
+  ) {
+    const params = this.getEvaluateParams(
+      'contextTarget',
+      browsingContextId,
+      sandbox,
+      expression,
+      awaitPromise,
+      resultOwnership
+    )
+
+    const command = {
+      method: 'script.evaluate',
+      params,
+    }
+
+    let response = await this.bidi.send(command)
+    return this.createEvaluateResult(response)
+  }
+
+  getCallFunctionParams(
+    targetType,
+    id,
+    sandbox,
+    functionDeclaration,
+    awaitPromise,
+    argumentValueList = null,
+    thisParameter = null,
+    resultOwnership = null
+  ) {
+    const params = {
+      functionDeclaration: functionDeclaration,
+      awaitPromise: awaitPromise,
+    }
+    if (targetType === 'contextTarget') {
+      if (sandbox != null) {
+        params['target'] = { context: id, sandbox: sandbox }
+      } else {
+        params['target'] = { context: id }
+      }
+    } else {
+      params['target'] = { realm: id }
+    }
+
+    if (argumentValueList != null) {
+      let argumentParams = []
+      argumentValueList.forEach((argumentValue) => {
+        argumentParams.push(argumentValue.asMap())
+      })
+      params['arguments'] = argumentParams
+    }
+
+    if (thisParameter != null) {
+      params['this'] = thisParameter
+    }
+
+    if (resultOwnership != null) {
+      params['resultOwnership'] = resultOwnership
+    }
+
+    return params
+  }
+
+  getEvaluateParams(
+    targetType,
+    id,
+    sandbox,
+    expression,
+    awaitPromise,
+    resultOwnership = null
+  ) {
+    const params = {
+      expression: expression,
+      awaitPromise: awaitPromise,
+    }
+    if (targetType === 'contextTarget') {
+      if (sandbox != null) {
+        params['target'] = { context: id, sandbox: sandbox }
+      } else {
+        params['target'] = { context: id }
+      }
+    } else {
+      params['target'] = { realm: id }
+    }
+    if (resultOwnership != null) {
+      params['resultOwnership'] = resultOwnership
+    }
+
+    return params
+  }
+
+  createEvaluateResult(response) {
+    var type = response.result.type
+    var realmId = response.result.realm
+    var evaluateResult
+
+    if (type === EvaluateResultType.SUCCESS) {
+      var result = response.result.result
+      evaluateResult = new EvaluateResultSuccess(
+        realmId,
+        new RemoteValue(result)
+      )
+    } else {
+      var exceptionDetails = response.result.exceptionDetails
+      evaluateResult = new EvaluateResultException(
+        realmId,
+        new ExceptionDetails(exceptionDetails)
+      )
+    }
+    return evaluateResult
+  }
+
+  realmInfoMapper(realms) {
+    var realmsList = []
+    realms.forEach((realm) => {
+      realmsList.push(RealmInfo.fromJson(realm))
+    })
+    return realmsList
+  }
+
+  async getAllRealms() {
+    const command = {
+      method: 'script.getRealms',
+      params: {},
+    }
+    let response = await this.bidi.send(command)
+    return this.realmInfoMapper(response.result.realms)
+  }
+
+  async getRealmsByType(type) {
+    const command = {
+      method: 'script.getRealms',
+      params: { type: type },
+    }
+    let response = await this.bidi.send(command)
+    return this.realmInfoMapper(response.result.realms)
+  }
+
+  async getRealmsInBrowsingContext(browsingContext) {
+    const command = {
+      method: 'script.getRealms',
+      params: { context: browsingContext },
+    }
+    let response = await this.bidi.send(command)
+    return this.realmInfoMapper(response.result.realms)
+  }
+
+  async getRealmsInBrowsingContextByType(browsingContext, type) {
+    const command = {
+      method: 'script.getRealms',
+      params: { context: browsingContext, type: type },
+    }
+    let response = await this.bidi.send(command)
+    return this.realmInfoMapper(response.result.realms)
+  }
+}
+
+async function getScriptManagerInstance(browsingContextId, driver) {
+  let instance = new ScriptManager(driver)
+  await instance.init(browsingContextId)
+  return instance
+}
+
+module.exports = getScriptManagerInstance

package/chrome.js

@@ -130,7 +130,6 @@
 const io = require('./io')
 const { Browser } = require('./lib/capabilities')
 const chromium = require('./chromium')
-const { driverLocation } = require('./common/seleniumManager')
 
 /**
  * Name of the ChromeDriver executable.
@@ -158,23 +157,6 @@ class ServiceBuilder extends chromium.ServiceBuilder {
    */
   constructor(opt_exe) {
     let exe = opt_exe || locateSynchronously()
-
-    if (!exe) {
-      try {
-        exe = driverLocation(Browser.CHROME)
-      } catch (err) {
-        console.log(`Unable to obtain driver using Selenium Manager: ${err}`)
-      }
-    }
-
-    if (!exe) {
-      throw Error(
-        `ChromeDriver could not be found on the PATH.
-        For more information on how to install drivers see
-        https://www.selenium.dev/documentation/webdriver/getting_started/install_drivers/.`
-      )
-    }
-
     super(exe)
   }
 }

package/chromium.js

@@ -83,6 +83,7 @@ const error = require('./lib/error')
 const Symbols = require('./lib/symbols')
 const webdriver = require('./lib/webdriver')
 const remote = require('./remote')
+const { getPath } = require('./common/driverFinder')
 
 /**
  * Custom command names supported by Chromium WebDriver.
@@ -684,6 +685,9 @@ class Driver extends webdriver.WebDriver {
       configureExecutor(executor, this.VENDOR_COMMAND_PREFIX)
     } else {
       let service = opt_serviceExecutor || this.getDefaultService()
+      if (!service.getExecutable()) {
+        service.setExecutable(getPath(service, caps))
+      }
       onQuit = () => service.kill()
       executor = createExecutor(service.start(), this.VENDOR_COMMAND_PREFIX)
     }

package/common/driverFinder.js

@@ -0,0 +1,59 @@
+// 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.
+
+/**
+ *  This implementation is still in beta, and may change.
+ *
+ *  Utility to find if a given file is present and executable.
+ */
+
+const { driverLocation } = require('./seleniumManager')
+const fs = require('fs')
+
+/**
+ * Determines the path of the correct Selenium Manager binary
+ * @returns {string}
+ */
+function getPath(service, capabilities) {
+  try {
+    return pathExists(service.getExecutable()) || driverLocation(capabilities)
+  } catch (e) {
+      throw Error(
+        `Unable to obtain browser driver.
+        For more information on how to install drivers see
+        https://www.selenium.dev/documentation/webdriver/getting_started/install_drivers/. ${e}`
+      )
+  }
+}
+
+/**
+ * _Synchronously_ attempts to locate the driver executable on the current
+ * system.
+ *
+ * @param {!string} driverPath
+ *
+ * @return {?string} the located executable, or `null`.
+ */
+function pathExists(driverPath) {
+  if (!driverPath || !fs.existsSync(driverPath)) {
+    return null
+  }
+  return driverPath
+}
+
+// PUBLIC API
+module.exports = { getPath }

package/common/seleniumManager.js

@@ -24,13 +24,13 @@
 const { platform } = require('process')
 const path = require('path')
 const fs = require('fs')
-const execSync = require('child_process').execSync
+const spawnSync = require('child_process').spawnSync
 
 /**
  * currently supported browsers for selenium-manager
  * @type {string[]}
  */
-const Browser = ['chrome', 'firefox', 'edge', 'iexplorer']
+const Browser = ['chrome', 'firefox', 'edge', 'MicrosoftEdge', 'iexplorer']
 
 /**
  * Determines the path of the correct Selenium Manager binary
@@ -47,7 +47,14 @@ function getBinary() {
   const file =
     directory === 'windows' ? 'selenium-manager.exe' : 'selenium-manager'
 
-  const filePath = path.join(__dirname, '..', '/bin', directory, file)
+  let seleniumManagerBasePath
+  if (process.env.SELENIUM_MANAGER_BASE_PATH) {
+    seleniumManagerBasePath = process.env.SELENIUM_MANAGER_BASE_PATH
+  } else {
+    seleniumManagerBasePath = path.join(__dirname, '..', '/bin')
+  }
+
+  const filePath = path.join(seleniumManagerBasePath, directory, file)
 
   if (!fs.existsSync(filePath)) {
     throw new Error(`Unable to obtain Selenium Manager`)
@@ -58,35 +65,55 @@ function getBinary() {
 
 /**
  * Determines the path of the correct driver
- * @param {Browser|string} browser name to fetch the driver
+ * @param {Capabilities} options browser options to fetch the driver
  * @returns {string} path of the driver location
  */
 
-function driverLocation(browser) {
-  if (!Browser.includes(browser.toLocaleString())) {
+function driverLocation(options) {
+  if (!Browser.includes(options.getBrowserName().toLocaleString())) {
     throw new Error(
-      `Unable to locate driver associated with browser name: ${browser}`
+      `Unable to locate driver associated with browser name: ${options.getBrowserName()}`
     )
   }
 
-  let args = [getBinary(), '--browser', browser, '--output', 'json']
-  let output
+  let args = ['--browser', options.getBrowserName(), '--output', 'json']
+
+  if (options.getBrowserVersion() && options.getBrowserVersion() !== "") {
+    args.push("--browser-version", options.getBrowserVersion())
+  }
+
+  const vendorOptions = options.get('goog:chromeOptions') || options.get('ms:edgeOptions')
+                        || options.get('moz:firefoxOptions')
+  if (vendorOptions && vendorOptions.binary && vendorOptions.binary !== "") {
+    args.push("--browser-path", '"' + vendorOptions.binary + '"')
+  }
 
+  const smBinary = getBinary()
+  const spawnResult = spawnSync(smBinary, args)
+  let output
+  if (spawnResult.status) {
+    let errorMessage
+    if (spawnResult.stderr.toString()) {
+      errorMessage = spawnResult.stderr.toString()
+    }
+    if (spawnResult.stdout.toString()) {
+      try {
+        output = JSON.parse(spawnResult.stdout.toString())
+        errorMessage = output.result.message
+      } catch (e) {
+        errorMessage = e.toString()
+      }
+    }
+    throw new Error(`Error executing command for ${smBinary} with ${args}: ${errorMessage}`)
+  }
   try {
-    output = JSON.parse(execSync(args.join(' ')).toString())
+    output = JSON.parse(spawnResult.stdout.toString())
   } catch (e) {
-    let error
-    try {
-      error = JSON.parse(e.stdout.toString()).result.message
-    } catch (e) {
-      error = e.toString()
-    }
-    throw new Error(
-      `Error executing command with ${args}: ${error}`
-    )
+    throw new Error(`Error executing command for ${smBinary} with ${args}: ${e.toString()}`)
   }
 
-  for (const key in output.logs){
+
+  for (const key in output.logs) {
     if (output.logs[key].level === 'WARN') {
       console.warn(`${output.logs[key].message}`)
     }

package/edge.js

@@ -80,7 +80,6 @@
 const { Browser } = require('./lib/capabilities')
 const io = require('./io')
 const chromium = require('./chromium')
-const { driverLocation } = require('./common/seleniumManager')
 
 /**
  * Name of the EdgeDriver executable.
@@ -107,22 +106,6 @@ class ServiceBuilder extends chromium.ServiceBuilder {
    */
   constructor(opt_exe) {
     let exe = opt_exe || locateSynchronously()
-
-    if (!exe) {
-      try {
-        exe = driverLocation('edge')
-      } catch (err) {
-        console.log(`Unable to obtain driver using Selenium Manager: ${err}`)
-      }
-    }
-
-    if (!exe) {
-      throw Error(
-        `MSEdgeDriver could not be found on the PATH.
-        For more information on how to install drivers see
-        https://www.selenium.dev/documentation/webdriver/getting_started/install_drivers/.`
-      )
-    }
     super(exe)
     this.setLoopback(true)
   }