selenium-webdriver 3.5.0 → 4.0.0-alpha.4

package/CHANGES.md

@@ -1,3 +1,249 @@
+## v4.0.0-alpha.4
+
+### Changes
+
+* Removed BUILD.bazel files from the build artifact
+
+
+## v4.0.0-alpha.3
+
+### Notice
+
+*  The minimum supported version of Node is now 10.15.0 LTS
+
+### Changes
+
+* add `pollTimeout` argument to the `wait()` method. Default value is `200`ms
+* add `switchTo().parentFrame()` for non-W3C compatible drivers
+* add support for opening a new window
+
+### API Changes
+
+*  Export `lib/input.Origin` from the top level `selenium-webdriver` module.
+*  HTTP requests from this library will now include a User-Agent of the form
+   `selenium/${VERSION} (js ${PLATFORM})`.
+
+
+## v4.0.0-alpha.1
+
+### Notice
+
+*  The minimum supported version of Node is now 8.9.0 LTS
+
+### Changes to Supported Browsers
+
+Native support has been removed for Opera and PhantomJS as the WebDriver
+implementations for these browsers are no longer under active development.
+
+For Opera, users should be able to simply rely on testing Chrome as the Opera
+browser is based on Chromium (and the operadriver was a thin wrapper around
+chromedriver). For PhantomJS, users should use Chrome or Firefox in headless
+mode (see `example/headless.js`)
+
+### Changes for W3C WebDriver Spec Compliance
+
+*  Revamped the actions API to conform with the WebDriver Spec:
+   <https://www.w3.org/TR/webdriver/#actions>. For details, refer to the JS doc
+   on the `lib/input.Actions` class.
+
+   As of January, 2018, only Firefox natively supports this new API. You can
+   put the `Actions` class into "bridge mode" and it will attempt to translate
+   mouse and keyboard actions to the legacy API (see class docs). Alternatively,
+   you may continue to use the legacy API directly via the `lib/actions` module.
+   __NOTE:__ The legacy API is considered strongly deprecated and will be
+   removed in a minor release once Google's Chrome and Microsoft's Edge browsers
+   support the new API.
+
+*  All window manipulation commands are now supported.
+*  Added `driver.switchTo().parentFrame()`
+*  When a named cookie is requested, attempt to fetch it directly using the
+   W3C endpoint, `GET /session/{session id}/cookie/{name}`. If this command is
+   not recognized by the remote end, fallback to fetching all cookies and then
+   searching for the desired name.
+*  Replaced `WebElement.getSize()` and `WebElement.getLocation()` with a single
+   method, `WebElement.getRect()`.
+
+### API Changes
+
+*  The core WebDriver API no longer uses promise manager
+   -  Removed `index.Builder#setControlFlow()`
+   -  The following thenable types no longer have a `cancel()` method:
+     -  The dynamically generated thenable WebDrivers created by `index.Builder`
+     -  `lib/webdriver.AlertPromise`
+     -  `lib/webdriver.WebElementPromise`
+*  Removed `remote/index.DriverService.prototype.stop()` (use `#kill()` instead)
+*  Removed the `lib/actions` module
+*  Removed the `lib/events` module
+*  Removed the `phantomjs` module
+*  Removed the 'opera' module
+*  Removed the promise manager from `lib/promise`, which includes the removal
+   of the following exported names (replacements, if any, in parentheses):
+   -  CancellableThenable
+   -  CancellationError
+   -  ControlFlow
+   -  Deferred
+   -  LONG_STACK_TRACES
+   -  MultipleUnhandledRejectionError
+   -  Promise (use native Promises)
+   -  Resolver
+   -  Scheduler
+   -  Thenable
+   -  USE_PROMISE_MANAGER
+   -  all (use Promise.all)
+   -  asap (use Promise.resolve)
+   -  captureStackTrace (use Error.captureStackTrace)
+   -  consume (use async functions)
+   -  controlFlow
+   -  createPromise (use new Promise)
+   -  defer
+   -  fulfilled (use Promise.resolve)
+   -  isGenerator
+   -  rejected (use Promise.reject)
+   -  setDefaultFlow
+   -  when (use Promise.resolve)
+*  Changes to the `Builder` class:
+   -  Added setChromeService, setEdgeService, & setFirefoxService
+   -  Removed setEnableNativeEvents
+   -  Removed setScrollBehavior
+*  Changes to `chrome.Driver`
+   -  Added sendDevToolsCommand
+   -  Added setDownloadPath
+*  Changes to `chrome.Options`
+   -  Now extends the `Capabilities` class
+   -  Removed from/toCapabilities
+*  Changes to `edge.Options`
+   -  Now extends the `Capabilities` class
+   -  Removed from/toCapabilities
+*  Changes to `ie.Options`
+   -  Now extends the `Capabilities` class
+   -  Removed from/toCapabilities
+*  Removed the `firefox.Binary` class. Custom binaries can still be selected
+   using `firefox.Options#setBinary()`. Likewise, custom binary arguments can be
+   specified with `firefox.Options#addArguments()`.
+*  Changes to `firefox.Driver`
+   -  Added installAddon(path)
+   -  Added uninstallAddon(id)
+*  Changes to `firefox.Options`
+   -  Now extends the `Capabilities` class
+   -  Removed from/toCapabilities
+   -  Removed setLoggingPreferences (was a no-op)
+   -  setProfile now only accepts a path to an existing profile
+   -  Added addExtensions
+   -  Added setPreference
+*  Removed the `firefox.Profile` class. All of its functionality is now
+   provided directly by `firefox.Options`
+*  Removed the `firefox/binary` module
+*  Removed the `firefox/profile` module
+*  Changes to `safari.Options`
+   -  Now extends the `Capabilities` class
+   -  Removed from/toCapabilities
+   -  Removed setCleanSession (was a no-op)
+*  Changes to `lib/capabilities.Browser`:
+   -  Removed several enum values.
+      -  ANDROID (use Chrome for Android; see docs on the chrome module)
+      -  IPAD (no support available)
+      -  IPHONE (no support available)
+      -  OPERA (use Chrome)
+      -  PHANTOM_JS (use Chrome or Firefox in headless mode)
+      -  HTMLUNIT (use Chrome or Firefox in headless mode)
+*  Changes to `lib/capabilities.Capabilities`:
+   -  Removed static factory methods android(), ipad(), iphone(), opera(),
+      phantomjs(), htmlunit(), and htmlunitwithjs(). Users can still manually
+      configure capabilities for these, but their use is not recommended and
+      they will no longer be surfaced in the API.
+*  Changes to `lib/error`:
+   -   Added
+       -   ElementClickInterceptedError
+       -   InsecureCertificateError
+       -   InvalidCoordinatesError
+       -   NoSuchCookieError
+   -   Removed
+       -  ElementNotVisibleError
+       -  InvalidElementCoordinatesError
+*  Changes to `lib/webdriver.WebDriver`:
+   -  Dropped support for "requiredCapabilities" from WebDriver.createSession
+   -  actions() now returns the new `lib/input.Actions` class
+   -  Removed touchActions
+   -  Renamed schedule to execute
+   -  Removed the `WebDriver.attachToSession()` factory method. Users can just
+      the `WebDriver` constructor directly instead.
+   -  Removed the `call()` method. This was used to inject custom function calls
+      into the control flow. Now that the promise manager is no longer used,
+      this method is no longer necessary. Users are now responsible for
+      coordinating actions (ideally with async functions) and can just call
+      functions directly instead of through `driver.call()`.
+*  Changes to `lib/webdriver.WebElement`:
+   -  Replaced getSize & getLocation with getRect
+*  Changes to `lib/webdriver.Alert`:
+   -  Removed authenticateAs
+*  Changes to `lib/webdriver.Options` (`driver.manage()`):
+   -  Removed timeouts (use get/setTimeouts)
+*  Changes to `lib/webdriver.Window` (`driver.manage().window()`):
+   -   Added
+       -  getRect
+       -  setRect
+       -  fullscreen
+       -  minimize
+   -   Removed (use the getRect/setRect methods)
+       -  getPosition
+       -  setPosition
+       -  getSize
+       -  setSize
+*  Removed the `testing/assert` module
+*  Changes to `testing/index`
+   -  Since the promise manager has been removed, it is no longer necessary to
+      wrap the Mocha test hooks; instead, users can simply use async functions.
+      The following have all been removed:
+      -  describe
+      -  before
+      -  beforeEach
+      -  after
+      -  afterEach
+      -  it
+   -  Added the `suite` function. For details, refer to the jsdoc or
+      `example/google_search_test.js`
+
+
+
+## v3.6.0
+
+### Bug Fixes
+
+* The Capabilities factory methods should only specify the name of the browser.
+* Protect against the remote end sometimes not returning a list to findElements
+  commands.
+* Properly reset state in `remote.DriverService#kill()`
+* The firefox module will no longer apply the preferences required by the legacy
+  FirefoxDriver. These preferences were only required when using the legacy
+  driver, support for which was dropped in v3.5.0.
+
+### API Changes
+
+* Added new methods to `selenium-webdriver/firefox.Options`:
+  - addArguments()
+  - headless()
+  - windowSize()
+* Deprecated `selenium-webdriver/firefox/binary.Binary`
+* Removed `selenium-webdriver/firefox.Options#useGeckoDriver()`
+* Removed the unused `selenium-webdriver/firefox/profile.decode()`
+* Removed methods from `selenium-webdriver/firefox/profile.Profile` that had
+  no effect since support for the legacy FirefoxDriver was dropped in 3.5.0:
+  - setNativeEventsEnabled
+  - nativeEventsEnabled
+  - getPort
+  - setPort
+* Removed `selenium-webdriver/firefox.ServiceBuilder#setFirefoxBinary()`; custom
+  binaries should be configured through the `firefox.Options` class.
+* Removed `selenium-webdriver/firefox.Capability`. These hold overs from the
+  legacy FirefoxDriver are no longer supported.
+
+### Changes for W3C WebDriver Spec Compliance
+
+* Deprecated `error.ElementNotVisibleError` in favor of the more generic
+  `error.ElementNotInteractableError`.
+* Support the `httpOnly` option when adding a cookie.
+
+
 ## v3.5.0
 
 ### Notice

package/LICENSE

@@ -187,7 +187,7 @@
       same "printed page" as the copyright notice for easier
       identification within third-party archives.
 
-   Copyright 2016 Software Freedom Conservancy (SFC)
+   Copyright 2019 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-2017 Software Freedom Conservancy
+Copyright 2011-2019 Software Freedom Conservancy
 Copyright 2004-2011 Selenium committers

package/README.md

@@ -11,11 +11,11 @@ Selenium may be installed via npm with
     npm install selenium-webdriver
 
 You will need to download additional components to work with each of the major
-browsers. The drivers for Chrome, Firefox, PhantomJS, Opera, and
-Microsoft's IE and Edge web browsers are all standalone executables that should
-be placed on your system [PATH]. Apple's safaridriver is shipped with
-Safari 10 for OS X El Capitan and macOS Sierra. You will need to enable Remote
-Automation in the Develop menu of Safari 10 before testing.
+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 is shipped with Safari 10 for OS X El Capitan and
+macOS Sierra. You will need to enable Remote Automation in the Develop menu of
+Safari 10 before testing.
 
 
 | Browser           | Component                          |
@@ -24,8 +24,6 @@ Automation in the Develop menu of Safari 10 before testing.
 | Internet Explorer | [IEDriverServer.exe][release]      |
 | Edge              | [MicrosoftWebDriver.msi][edge]     |
 | Firefox           | [geckodriver(.exe)][geckodriver]   |
-| PhantomJS         | [phantomjs(.exe)][phantomjs]       |
-| Opera             | [operadriver(.exe)][opera]         |
 | Safari            | [safaridriver]                     |
 
 ## Usage
@@ -33,19 +31,20 @@ Automation in the Develop menu of Safari 10 before testing.
 The sample below and others are included in the `example` directory. You may
 also find the tests for selenium-webdriver informative.
 
-    var webdriver = require('selenium-webdriver'),
-        By = webdriver.By,
-        until = webdriver.until;
-
-    var driver = new webdriver.Builder()
-        .forBrowser('firefox')
-        .build();
-
-    driver.get('http://www.google.com/ncr');
-    driver.findElement(By.name('q')).sendKeys('webdriver');
-    driver.findElement(By.name('btnG')).click();
-    driver.wait(until.titleIs('webdriver - Google Search'), 1000);
-    driver.quit();
+```javascript
+const {Builder, By, Key, until} = require('selenium-webdriver');
+
+(async function example() {
+  let driver = await new Builder().forBrowser('firefox').build();
+  try {
+    await driver.get('http://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();
+  }
+})();
+```
 
 ### Using the Builder API
 
@@ -54,15 +53,17 @@ instances. Rather than clutter your code with branches for the various browsers,
 the builder lets you set all options in one flow. When you call
 `Builder#build()`, all options irrelevant to the selected browser are dropped:
 
-    var webdriver = require('selenium-webdriver'),
-        chrome = require('selenium-webdriver/chrome'),
-        firefox = require('selenium-webdriver/firefox');
+```javascript
+const webdriver = require('selenium-webdriver');
+const chrome = require('selenium-webdriver/chrome');
+const firefox = require('selenium-webdriver/firefox');
 
-    var driver = new webdriver.Builder()
-        .forBrowser('firefox')
-        .setChromeOptions(/* ... */)
-        .setFirefoxOptions(/* ... */)
-        .build();
+let driver = new webdriver.Builder()
+    .forBrowser('firefox')
+    .setChromeOptions(/* ... */)
+    .setFirefoxOptions(/* ... */)
+    .build();
+```
 
 Why would you want to configure options irrelevant to the target browser? The
 `Builder`'s API defines your _default_ configuration. You can change the target
@@ -95,11 +96,12 @@ server with
 You may configure your tests to run against a remote server through the Builder
 API:
 
-    var driver = new webdriver.Builder()
-        .forBrowser('firefox')
-        .usingServer('http://localhost:4444/wd/hub')
-        .build();
-
+```javascript
+let driver = new webdriver.Builder()
+    .forBrowser('firefox')
+    .usingServer('http://localhost:4444/wd/hub')
+    .build();
+```
 Or change the Builder's configuration at runtime with the `SELENIUM_REMOTE_URL`
 environment variable:
 
@@ -165,11 +167,11 @@ months, the support window for selenium-webdriver will be roughly:
 
 | Date      | LTS  | Stable |
 | --------- | ---: | -----: |
-| (current) |  6.9 |    7.5 |
-| 2017-04   |  6.0 |    8.0 |
-| 2017-10   |  8.0 |    9.0 |
-| 2018-04   |  8.0 |   10.0 |
-| 2018-10   | 10.0 |   11.0 |
+| (current) |  8.9 |    9.0 |
+| 2018-04   |  8.x |   10.0 |
+| 2018-10   | 10.x |   11.0 |
+| 2019-04   | 10.x |   12.0 |
+| 2019-10   | 12.x |   13.0 |
 
 ## Issues
 
@@ -219,8 +221,6 @@ under the License.
 [chrome]: http://chromedriver.storage.googleapis.com/index.html
 [gh]: https://github.com/SeleniumHQ/selenium/
 [issues]: https://github.com/SeleniumHQ/selenium/issues
-[opera]: https://github.com/operasoftware/operachromiumdriver/releases
-[phantomjs]: http://phantomjs.org/
 [edge]: http://go.microsoft.com/fwlink/?LinkId=619687
 [geckodriver]: https://github.com/mozilla/geckodriver/releases/
 [reduction]: http://www.webkit.org/quality/reduction.html