selenium-webdriver 4.18.0 → 4.19.0

package/README.md

@@ -13,19 +13,18 @@ Selenium may be installed via npm with
 You will need to download additional components to work with each of the major
 browsers. The drivers for Chrome, Firefox, and Microsoft's IE and Edge web
 browsers are all standalone executables that should be placed on your system
-[PATH]. Apple's safaridriver (v10 and above) can be found at the 
-following path – /usr/bin/safaridriver. To enable automation on safari, 
+[PATH]. Apple's safaridriver (v10 and above) can be found at the
+following path – /usr/bin/safaridriver. To enable automation on safari,
 you need to run command `safaridriver --enable`.
 
-
-| Browser            | Component                           |
-|:-------------------|:------------------------------------|
-| Chrome             | [chromedriver(.exe)][chrome]        |
-| Internet Explorer  | [IEDriverServer.exe][release]       |
-| Edge               | [MicrosoftWebDriver.msi][edge]      |
-| Firefox            | [geckodriver(.exe)][geckodriver]    |
-| Opera              | [operadriver(.exe)][operadriver]    |
-| Safari             | [safaridriver]                      |
+| Browser           | Component                        |
+| :---------------- | :------------------------------- |
+| Chrome            | [chromedriver(.exe)][chrome]     |
+| Internet Explorer | [IEDriverServer.exe][release]    |
+| Edge              | [MicrosoftWebDriver.msi][edge]   |
+| Firefox           | [geckodriver(.exe)][geckodriver] |
+| Opera             | [operadriver(.exe)][operadriver] |
+| Safari            | [safaridriver]                   |
 
 ## Usage
 
@@ -33,18 +32,18 @@ The sample below and others are included in the `example` directory. You may
 also find the tests for selenium-webdriver informative.
 
 ```javascript
-const {Builder, Browser, By, Key, until} = require('selenium-webdriver');
+const { Builder, Browser, By, Key, until } = require('selenium-webdriver')
 
-(async function example() {
-  let driver = await new Builder().forBrowser(Browser.FIREFOX).build();
+;(async function example() {
+  let driver = await new Builder().forBrowser(Browser.FIREFOX).build()
   try {
-    await driver.get('https://www.google.com/ncr');
-    await driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN);
-    await driver.wait(until.titleIs('webdriver - Google Search'), 1000);
+    await driver.get('https://www.google.com/ncr')
+    await driver.findElement(By.name('q')).sendKeys('webdriver', Key.RETURN)
+    await driver.wait(until.titleIs('webdriver - Google Search'), 1000)
   } finally {
-    await driver.quit();
+    await driver.quit()
   }
-})();
+})()
 ```
 
 ### Using the Builder API
@@ -55,15 +54,15 @@ the builder lets you set all options in one flow. When you call
 `Builder#build()`, all options irrelevant to the selected browser are dropped:
 
 ```javascript
-const webdriver = require('selenium-webdriver');
-const chrome = require('selenium-webdriver/chrome');
-const firefox = require('selenium-webdriver/firefox');
+const webdriver = require('selenium-webdriver')
+const chrome = require('selenium-webdriver/chrome')
+const firefox = require('selenium-webdriver/firefox')
 
 let driver = new webdriver.Builder()
-    .forBrowser(webdriver.Browser.FIREFOX)
-    .setChromeOptions(/* ... */)
-    .setFirefoxOptions(/* ... */)
-    .build();
+  .forBrowser(webdriver.Browser.FIREFOX)
+  .setChromeOptions(/* ... */)
+  .setFirefoxOptions(/* ... */)
+  .build()
 ```
 
 Why would you want to configure options irrelevant to the target browser? The
@@ -99,10 +98,11 @@ API:
 
 ```javascript
 let driver = new webdriver.Builder()
-    .forBrowser(webdriver.Browser.FIREFOX)
-    .usingServer('http://localhost:4444/wd/hub')
-    .build();
+  .forBrowser(webdriver.Browser.FIREFOX)
+  .usingServer('http://localhost:4444/wd/hub')
+  .build()
 ```
+
 Or change the Builder's configuration at runtime with the `SELENIUM_REMOTE_URL`
 environment variable:
 
@@ -135,82 +135,83 @@ will also have "best effort" support. Releases older than the latest LTS,
 _semver-major_ releases, and all unstable release branches (e.g. "v.Next")
 are considered strictly unsupported.
 
-For example, suppose the current LTS and stable releases are v14.20.0 and v18.8.0,
+For example, suppose the current LTS and stable releases are v14.20.0 and
+v18.8.0,
 respectively. Then a Selenium release would have the following support levels:
 
-|  Version   |     Support     |
-|:----------:|:---------------:|
-|  <= 14.19  |  _unsupported_  |
-|  14.20.0   |    supported    |
-|   18.0-7   |   best effort   |
-|   18.8.0   |    supported    |
-| >= 18.8.0  |   best effort   |
-|   v.Next   |  _unsupported_  |
+|  Version  |    Support    |
+| :-------: | :-----------: |
+| <= 14.19  | _unsupported_ |
+|  14.20.0  |   supported   |
+|  18.0-7   |  best effort  |
+|  18.8.0   |   supported   |
+| >= 18.8.0 |  best effort  |
+|  v.Next   | _unsupported_ |
 
 ### Support Level Definitions
 
 - _supported:_ A selenium-webdriver release will be API compatible with the
-    platform API, without the use of runtime flags.
+  platform API, without the use of runtime flags.
 
 - _best effort:_ Bugs will be investigated as time permits. API compatibility is
-    only guaranteed where required by a _supported_ release. This effectively
-    means the adoption of new JS features, such as ES2015 modules, will depend
-    on what is supported in Node's LTS.
+  only guaranteed where required by a _supported_ release. This effectively
+  means the adoption of new JS features, such as ES2015 modules, will depend
+  on what is supported in Node's LTS.
 
 - _unsupported:_ Bug submissions will be closed as will-not-fix and API
-    compatibility is not guaranteed.
+  compatibility is not guaranteed.
 
 ### Projected Support Schedule
 
 If Node releases a new [LTS] each October and a new major version every 6
 months, the support window for selenium-webdriver will be roughly:
 
-|  Release  |      Status      | END-OF-LIFE  |
-|:---------:|:----------------:|:------------:|
-|   v14.x   | Maintenance LTS  |  2023-04-30  |
-|   v16.x   |    Active LTS    |  2023-09-11  |
-|   v18.x   |     Current      |  2025-04-30  |
-|   v19.x   |     Pending      |  2023-06-01  |
-|    v20    |     Pending      |  2026-04-30  |
+| Release |     Status      | END-OF-LIFE |
+| :-----: | :-------------: | :---------: |
+|  v14.x  | Maintenance LTS | 2023-04-30  |
+|  v16.x  |   Active LTS    | 2023-09-11  |
+|  v18.x  |     Current     | 2025-04-30  |
+|  v19.x  |     Pending     | 2023-06-01  |
+|   v20   |     Pending     | 2026-04-30  |
 
 ## Issues
 
 Please report any issues using the [Selenium issue tracker][issues]. When using
 the issue tracker
 
-- __Do__ include a detailed description of the problem.
-- __Do__ include a link to a [gist](http://gist.github.com/) with any
-    interesting stack traces/logs (you may also attach these directly to the bug
-    report).
-- __Do__ include a [reduced test case][reduction]. Reporting "unable to find
-    element on the page" is _not_ a valid report - there's nothing for us to
-    look into. Expect your bug report to be closed if you do not provide enough
-    information for us to investigate.
-- __Do not__ use the issue tracker to submit basic help requests. All help
-    inquiries should be directed to the [user forum][users] or #selenium IRC
-    channel.
-- __Do not__ post empty "I see this too" or "Any updates?" comments. These
-    provide no additional information and clutter the log.
-- __Do not__ report regressions on closed bugs as they are not actively
-    monitored for updates (especially bugs that are >6 months old). Please open a
-    new issue and reference the original bug in your report.
+- **Do** include a detailed description of the problem.
+- **Do** include a link to a [gist](http://gist.github.com/) with any
+  interesting stack traces/logs (you may also attach these directly to the bug
+  report).
+- **Do** include a [reduced test case][reduction]. Reporting "unable to find
+  element on the page" is _not_ a valid report - there's nothing for us to
+  look into. Expect your bug report to be closed if you do not provide enough
+  information for us to investigate.
+- **Do not** use the issue tracker to submit basic help requests. All help
+  inquiries should be directed to the [user forum][users] or #selenium IRC
+  channel.
+- **Do not** post empty "I see this too" or "Any updates?" comments. These
+  provide no additional information and clutter the log.
+- **Do not** report regressions on closed bugs as they are not actively
+  monitored for updates (especially bugs that are >6 months old). Please open a
+  new issue and reference the original bug in your report.
 
 ## License
 
 Licensed to the Software Freedom Conservancy (SFC) under one
-or more contributor license agreements.  See the NOTICE file
+or more contributor license agreements. See the NOTICE file
 distributed with this work for additional information
-regarding copyright ownership.  The SFC licenses this file
+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
+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
+KIND, either express or implied. See the License for the
 specific language governing permissions and limitations
 under the License.
 
@@ -223,9 +224,7 @@ under the License.
 [edge]: http://go.microsoft.com/fwlink/?LinkId=619687
 [geckodriver]: https://github.com/mozilla/geckodriver/releases/
 [reduction]: http://www.webkit.org/quality/reduction.html
-
 [release]: https://www.selenium.dev/downloads/
-
 [users]: https://groups.google.com/forum/#!forum/selenium-users
 [safaridriver]: https://developer.apple.com/library/prerelease/content/releasenotes/General/WhatsNewInSafari/Articles/Safari_10_0.html#//apple_ref/doc/uid/TP40014305-CH11-DontLinkElementID_28
 [operadriver]: https://github.com/operasoftware/operachromiumdriver/releases

package/bidi/addInterceptParameters.js

@@ -15,7 +15,7 @@
 // specific language governing permissions and limitations
 // under the License.
 
-const {UrlPattern} = require("./urlPattern");
+const { UrlPattern } = require('./urlPattern')
 
 class AddInterceptParameters {
   #phases = []
@@ -23,64 +23,58 @@ class AddInterceptParameters {
 
   constructor(phases) {
     if (phases instanceof Array) {
-      phases.forEach(phase => this.#phases.push(phase))
+      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
+  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
+  }
 
-    urlStringPattern(pattern)
-    {
-      if (!pattern instanceof String) {
-        throw new Error(`Pattern must be an instance of String. Received:'${pattern}'`)
+  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
+  }
 
-      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
+  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
+  }
 
-    asMap()
-    {
-      const map = new Map()
-      map.set('phases', this.#phases)
-      if (this.#urlPatterns.length > 0) {
-        map.set('urlPatterns', this.#urlPatterns)
+  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
+  }
 
-      return map
+  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}
+module.exports = { AddInterceptParameters }

package/bidi/argumentValue.js

@@ -16,6 +16,7 @@
 // under the License.
 
 const { LocalValue } = require('./protocolValue')
+
 class ArgumentValue {
   constructor(value) {
     this.value = value

package/bidi/browser.js

@@ -0,0 +1,77 @@
+// 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 Browser {
+  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 createUserContext() {
+    const command = {
+      method: 'browser.createUserContext',
+      params: {},
+    }
+
+    let response = await this.bidi.send(command)
+
+    return response.result.userContext
+  }
+
+  async getUserContexts() {
+    const command = {
+      method: 'browser.getUserContexts',
+      params: {},
+    }
+
+    let response = await this.bidi.send(command)
+
+    let userContexts = []
+
+    let userContextsArray = response.result.userContexts
+
+    for (let userContextJson of userContextsArray) {
+      userContexts.push(userContextJson.userContext)
+    }
+
+    return userContexts
+  }
+
+  async removeUserContext(userContext) {
+    const command = {
+      method: 'browser.removeUserContext',
+      params: { userContext: userContext },
+    }
+
+    await this.bidi.send(command)
+  }
+}
+
+async function getBrowserInstance(driver) {
+  let instance = new Browser(driver)
+  await instance.init()
+  return instance
+}
+
+module.exports = getBrowserInstance

package/bidi/browsingContext.js

@@ -71,6 +71,13 @@ class BrowsingContext {
     this._driver = driver
   }
 
+  /**
+   * @returns id
+   */
+  get id() {
+    return this._id
+  }
+
   async init({ browsingContextId, type, referenceContext }) {
     if (!(await this._driver.getCapabilities()).get('webSocketUrl')) {
       throw Error('WebDriver instance must support BiDi protocol')
@@ -101,13 +108,6 @@ class BrowsingContext {
     return await this.bidi.send(params)
   }
 
-  /**
-   * @returns id
-   */
-  get id() {
-    return this._id
-  }
-
   /**
    * @param url the url to navigate to
    * @param readinessState type of readiness state: "none" / "interactive" / "complete"

package/bidi/continueRequestParameters.js

@@ -0,0 +1,83 @@
+// 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 { BytesValue, Header } = require('./networkTypes')
+
+class ContinueRequestParameters {
+  #map = new Map()
+
+  constructor(request) {
+    this.#map.set('request', request)
+  }
+
+  body(value) {
+    if (!(value instanceof BytesValue)) {
+      throw new Error(`Value must be an instance of BytesValue. Received: '${value})'`)
+    }
+    this.#map.set('body', Object.fromEntries(value.asMap()))
+    return this
+  }
+
+  cookies(cookieHeaders) {
+    const cookies = []
+    cookieHeaders.forEach((header) => {
+      if (!(header instanceof Header)) {
+        throw new Error(`CookieHeader must be an instance of Header. Received:'${header}'`)
+      }
+      cookies.push(Object.fromEntries(header.asMap()))
+    })
+
+    this.#map.set('cookies', cookies)
+    return this
+  }
+
+  headers(headers) {
+    const headerList = []
+    headers.forEach((header) => {
+      if (!(header instanceof Header)) {
+        throw new Error(`Header value must be an instance of Header. Received:'${header}'`)
+      }
+      headerList.push(Object.fromEntries(header.asMap()))
+    })
+
+    this.#map.set('headers', headerList)
+    return this
+  }
+
+  method(method) {
+    if (typeof method !== 'string') {
+      throw new Error(`Http method must be a string. Received: '${method})'`)
+    }
+    this.#map.set('method', method)
+    return this
+  }
+
+  url(url) {
+    if (typeof url !== 'string') {
+      throw new Error(`Url must be a string. Received:'${url}'`)
+    }
+
+    this.#map.set('url', url)
+    return this
+  }
+
+  asMap() {
+    return this.#map
+  }
+}
+
+module.exports = { ContinueRequestParameters }

package/bidi/continueResponseParameters.js

@@ -0,0 +1,89 @@
+// 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 { Header } = require('./networkTypes')
+
+class ContinueResponseParameters {
+  #map = new Map()
+
+  constructor(request) {
+    this.#map.set('request', request)
+  }
+
+  cookies(cookieHeaders) {
+    const cookies = []
+    cookieHeaders.forEach((header) => {
+      if (!(header instanceof Header)) {
+        throw new Error(`CookieHeader must be an instance of Header. Received:'${header}'`)
+      }
+      cookies.push(Object.fromEntries(header.asMap()))
+    })
+
+    this.#map.set('cookies', cookies)
+    return this
+  }
+
+  credentials(username, password) {
+    if (typeof username !== 'string') {
+      throw new Error(`Username must be a string. Received:'${username}'`)
+    }
+
+    if (typeof password !== 'string') {
+      throw new Error(`Password must be a string. Received:'${password}'`)
+    }
+
+    this.#map.set('credentials', { type: 'password', username: username, password: password })
+
+    return this
+  }
+
+  headers(headers) {
+    const headerList = []
+    headers.forEach((header) => {
+      if (!(header instanceof Header)) {
+        throw new Error(`Header value must be an instance of Header. Received:'${header}'`)
+      }
+      headerList.push(Object.fromEntries(header.asMap()))
+    })
+
+    this.#map.set('headers', headerList)
+    return this
+  }
+
+  reasonPhrase(reasonPhrase) {
+    if (typeof reasonPhrase !== 'string') {
+      throw new Error(`Reason phrase must be a string. Received: '${reasonPhrase})'`)
+    }
+    this.#map.set('reasonPhrase', reasonPhrase)
+    return this
+  }
+
+  statusCode(statusCode) {
+    if (!Number.isInteger(statusCode)) {
+      throw new Error(`Status must be an integer. Received:'${statusCode}'`)
+    }
+
+    this.#map.set('statusCode', statusCode)
+    return this
+  }
+
+  asMap() {
+    return this.#map
+  }
+}
+
+module.exports = { ContinueResponseParameters }