v.next

Changes

API Changes

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

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

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

Native support for Firefox 45 (ESR) has been removed. Users will have to connect
to a remote Selenium server that supports Firefox 45.

Changes

Removed native support for Firefox 46 and older.

The SELENIUM_MARIONETTE enviornment variable no longer has an effect.

selenium-webdriver/firefox.Capability.MARIONETTE is deprecated.

selenium-webdriver/firefox.Options#useGeckoDriver() is deprecated and now a no-op.

firefox.Options will no longer discard the "moz:firefoxOptions" set in
user provided capabilities (via Builder.withCapabilities({})). When both
are used, the settings in firefox.Options will be applied last.

Added chrome.Options#headless() and chrome.Options#windowSize(), which
may be used to start Chrome in headless mode (requires Chrome 59+) and to set
the initial window size, respectively.

When communicating with a W3C-compliant remote end, use the atoms library for
the WebElement.getAttribute() and WebElement.isDisplayed() commands. This
behavior is consistent with the java, .net, python, and ruby clients.

API Changes

Removed safari.Options#useLegacyDriver()

Reduced the API on promise.Thenable for compatibility with native promises:

Removed #isPending()

Removed #cancel()

Removed #finally()

Changed all subclasses of webdriver.WebDriver to overload the static
function WebDriver.createSession() instead of doing work in the
constructor. All constructors now inherit the base class' function signature.
Users are still encouraged to use the Builder class instead of creating
drivers directly.

Builder#build() now returns a "thenable" WebDriver instance, allowing users
to immediately schedule commands (as before), or issue them through standard
promise callbacks. This is the same pattern already employed for WebElements.

Removed Builder#buildAsync() as it was redundant with the new semantics of
build().

v3.0.0-beta-3

Fixed a bug where the promise manager would silently drop callbacks after
recovering from an unhandled promise rejection.

Added the firefox.ServiceBuilder class, which may be used to customize the
geckodriver used for firefox.Driver instances.

Added support for Safari 10 safaridriver. safaridriver may be disabled
via tha API, safari.Options#useLegacyDriver, to use the safari
extension driver.

Updated the lib/proxy module to support configuring a SOCKS proxy.

For the promise.ControlFlow, fire the "uncaughtException" event in a new
turn of the JS event loop. As a result of this change, any errors thrown by
an event listener will propagate to the global error handler. Previously,
this event was fired with in the context of a (native) promise callback,
causing errors to be silently suppressed in the promise chain.

API Changes

Added remote.DriverService.Builder as a base class for configuring
DriverService instances that run in a child-process. The
chrome.ServiceBuilder, edge.ServiceBuilder, and opera.ServiceBuilder
classes now all extend this base class with browser-specific options.

For each of the ServiceBuilder clases, renamed usingPort and
withEnvironment to setPort and setEnvironment, respectively.

Renamed chrome.ServiceBuilder#setUrlBasePath to #setPath

Changed the signature of the firefox.Driver from (config, flow, executor)
to (config, executor, flow).

Exposed the Condition and WebElementCondition classes from the top-level
selenium-webdriver module (these were previously only available from
lib/webdriver).

Removed the mandatory use of Firefox Dev Edition, when using Marionette driver

Fixed timeouts' URL

Properly send HTTP requests when using a WebDriver server proxy

Properly configure proxies when using the geckodriver

http.Executor now accepts a promised client. The builder.Builder class
will now use this instead of a command.DeferredExecutor when creating
WebDriver instances.

For Chrome and Firefox, the builder.Builder class will always return an
instanceof chrome.Driver and firefox.Driver, respectively, even when
configured to use a remote server (from builder.Builder#usingServer(url),
SELENIUM_REMOTE_URL, etc).

API Changes

promise.Deferred is no longer a thenable object.

Options#addCookie() now takes a record object instead of 7 individual
parameters. A TypeError will be thrown if addCookie() is called with invalid
arguments.

When adding cookies, the desired expiry must be provided as a Date or in
seconds since epoch. When retrieving cookies, the expiration is always
returned in seconds.

FIXED: properly handle responses from the remote end in
WebDriver.attachToSession

v2.53.1

FIXED: for consistency with the other language bindings, remote.FileDetector
will ignore paths that refer to a directory.

v2.53.0

Change Summary

Added preliminary support for Marionette, Mozilla's WebDriver implementation
for Firefox. Marionette may be enabled via the API,
firefox.Options#useMarionette, or by setting the SELENIUM_MARIONETTE
environment variable.

Moved all logic for parsing and interpreting responses from the remote end
into the individual command.Executor implementations.

For consistency with the other Selenium language bindings,
WebDriver#isElementPresent() and WebElement#isElementPresent() have
been deprecated. These methods will be removed in v3.0. Use the findElements
command to test for the presence of an element:

driver.findElements(By.css('.foo')).then(found => !!found.length);

Added support for W3C-spec compliant servers.

For consistent naming, deprecating error.InvalidSessionIdError in favor of
error.NoSuchSessionError.

Moved the error module to lib/error so all core modules are co-located.
The top-level error module will be removed in v3.0.

Moved until.Condition and until.WebElementCondition to the webdriver
module to break a circular dependency.

Added support for setting the username and password in basic auth pop-up
dialogs (currently IE only).

Deprecated WebElement#getInnerHtml() and WebEleemnt#getOuterHtml()

Deprecated Promise#thenCatch() - use Promise#catch() instead

Deprecated Promise#thenFinally() - use promise.thenFinally() instead

FIXED: io.findInPath() will no longer match against directories that have
the same basename as the target file.

FIXED: phantomjs.Driver now takes a third argument that defines the path to
a log file to use for the phantomjs executable's output. This may be quickly
set at runtime with the SELENIUM_PHANTOMJS_LOG environment variable.

Changes for W3C WebDriver Spec Compliance

Changed element.sendKeys(...) to send the key sequence as an array where
each element defines a single key. The legacy wire protocol permits arrays
where each element is a string of arbitrary length. This change is solely
at the protocol level and should have no user-visible effect.

v2.52.0

Notice

Starting with v2.52.0, each release of selenium-webdriver will support the
latest minor LTS and stable Node releases. All releases between the LTS and
stable release will have best effort support. Further details are available in
the selenium-webdriver package README.

Change Summary

Add support for Microsoft's Edge web browser

Added webdriver.Builder#buildAsync(), which returns a promise that will be
fulfilled with the newly created WebDriver instance once the associated
browser has been full initialized. This is purely a convenient alternative
to the existing build() method as the WebDriver class will always defer
commands until it has a fully created browser.

Added firefox.Profile#setHost() which may be used to set the host that
the FirefoxDriver's server listens for commands on. The server uses
"localhost" by default.

Added promise.Promise#catch() for API compatibility with native Promises.
promise.Promise#thenCatch() is not yet deprecated, but it simply
delegates to catch.

Changed some io operations to use native promises.

Changed command.Executor#execute() and HttpClient#send() to return
promises instead of using callback passing.

Replaced the Serializable class with an internal, Symbol-defined method.

Changed the Capabilities class to extend the native Map type.

Changed the Capabilities.has(key) to only test if a capability has been set
(Map semantics). To check whether the value is true, use get(key).

Deprecated executors.DeferredExecutor in favor of
lib/command.DeferredExecutor.

Changes for W3C WebDriver Spec Compliance

Updated the By locators that are not in the W3C spec to delegated to using
CSS selectors: By.className, By.id, By.name, and By.tagName.

v2.49-51

Releases skipped to stay in sync with the rest of the Selenium project

v2.48.2

Added WebElement#takeScreenshot().

More adjustments to promise callback tracking.

v2.48.1

FIXED: Adjusted how the control flow tracks promise callbacks to avoid a
potential deadlock.

v2.48.0

Node v0.12.x users must run with --harmony. This is the last release that
will support v0.12.x

FIXED: (Promise/A+ compliance) When a promise is rejected with a thenable,
the promise adopts the thenable as its rejection reason instead of waiting
for it to settle. The previous (incorrect) behavior was hidden by bugs in
the promises-aplus-tests compliance test suite that were fixed in version
2.1.1.

FIXED: the webdriver.promise.ControlFlow now has a consistent execution
order for tasks/callbacks scheduled in different turns of the JS event loop.
Refer to the webdriver.promise documentation for more details.

FIXED: do not drop user auth from the WebDriver server URL.

FIXED: a single firefox.Binary instance may be used to configure and
launch multiple FirefoxDriver sessions.

FIXED: zip files created for transfer to a remote WebDriver server are no
longer compressed. If the zip contained a file that was already compressed,
the server would return an "invalid code lengths set" error.

FIXED: Surfaced the loopback option to remote/SeleniumServer. When set,
the server will be accessed using the current host's loopback address.

v2.47.0

Notice

This is the last release for selenium-webdriver that will support ES5.
Subsequent releases will depend on ES6 features that are enabled by
default in Node v4.0.0. Node v0.12.x will
continue to be supported, but will require setting the --harmony flag.

FIXED: The promise.ControlFlow will maintain state for promise chains
generated in a loop.

FIXED: Correct serialize target elements used in an action sequence.

FIXED: promise.ControlFlow#wait() now has consistent semantics for an
omitted or 0-timeout: it will wait indefinitely.

FIXED: remote.DriverService#start() will now fail if the child process dies
while waiting for the server to start accepting requests. Previously, start
would continue to poll the server address until the timeout expired.

FIXED: Skip launching Firefox with the -silent flag to preheat the profile.
Starting with Firefox 38, this would cause the browser to crash. This step,
which was first introduced for Selenium's java client back with Firefox 2,
no longer appears to be required.

FIXED: 8564: firefox.Driver#quit() will wait for the Firefox process to
terminate before deleting the temporary webdriver profile. This eliminates a
race condition where Firefox would write profile data during shutdown,
causing the rm -rf operation on the profile directory to fail.

v2.45.1

FIXED: 8548: Task callbacks are once again dropped if the task was cancelled
due to a previously uncaught error within the frame.

v2.45.0

Important Policy Change

Starting with the 2.45.0 release, selenium-webdriver will support the last
two stable minor releases for Node. For 2.45.0, this means Selenium will
support Node 0.10.x and 0.12.x. Support for the intermediate, un-stable release
(0.11.x) is "best-effort". This policy will be re-evaluated once Node has a
major version release (i.e. 1.0.0).

The promise.ControlFlow class has been updated to track the asynchronous
breaks required by Promises/A+, so there are no changes to task execution
order.

Updated how errors are annotated on failures. When a task fails, the
stacktrace from when that task was scheduled is appended to the rejection
reason with a From: prefix (if it is an Error object). For example:

Error: element not found
Wait timed out after 2002ms
at <stack trace>
From: Task: element not found
at <stack trace>
From: Task: WebDriver.call(function)
at <stack trace>

Changed the format of strings returned by promise.ControlFlow#getSchedule.
This function now accepts a boolean to control whether the returned string
should include the stacktraces for when each task was scheduled.

Deprecating promise.ControlFlow#getHistory,
promise.ControlFlow#clearHistory, and promise.ControlFlow#annotateError.
These functions were all intended for internal use and are no longer
necessary, so they have been made no-ops.

WebDriver.wait() may now be used to wait for a promise to resolve, with
an optional timeout. Refer to the API documentation for more information.

Added support for copying files to a remote Selenium via sendKeys to test
file uploads. Refer to the API documentation for more information. Sample
usage included in test/upload_test.js

Expanded the interactions API to include touch actions.
See WebDriver.touchActions().

FIXED: 8380: firefox.Driver will delete its temporary profile on quit.

FIXED: 8306: Stack overflow in promise callbacks eliminated.

FIXED: 8221: Added support for defining custom command mappings. Includes
support for PhantomJS's executePhantomJS (requires PhantomJS 1.9.7 or
GhostDriver 1.1.0).

FIXED: 8128: When the FirefoxDriver marshals an object to the page for
executeScript, it defines additional properties (required by the driver's
implementation). These properties will no longer be enumerable and should
be omitted (i.e. they won't show up in JSON.stringify output).

FIXED: 8094: The control flow will no longer deadlock when a task returns
a promise that depends on the completion of sub-tasks.

v2.44.0

Added the until module, which defines common explicit wait conditions.
Sample usage:

FIXED: 8000: Builder.forBrowser() now accepts an empty string since some
WebDriver implementations ignore the value. A value must still be specified,
however, since it is a required field in WebDriver's wire protocol.

FIXED: 7994: The stacktrace module will not modify stack traces if the
initial parse fails (e.g. the user defined Error.prepareStackTrace)

FIXED: 5855: Added a module (until) that defines several common conditions
for use with explicit waits. See updated examples for usage.

v2.43.5

FIXED: 7905: Builder.usingServer(url) once again returns this for
chaining.

v2.43.2-4

No changes; version bumps while attempting to work around an issue with
publishing to npm (a version string may only be used once).

v2.43.1

Fixed an issue with flakiness when setting up the Firefox profile that could
prevent the driver from initializing properly.

v2.43.0

Added native support for Firefox - the Java Selenium server is no longer
required.

Added support for generator functions to ControlFlow#execute and
ControlFlow#wait. For more information, see documentation on
webdriver.promise.consume. Requires harmony support (run with
node --harmony-generators in v0.11.x).

Various improvements to the Builder API. Notably, the build() function
will no longer default to attempting to use a server at
http://localhost:4444/wd/hub if it cannot start a browser directly -
you must specify the WebDriver server with usingServer(url). You can
also set the target browser and WebDriver server through a pair of
environment variables. See the documentation on the Builder constructor
for more information.

For consistency with the other language bindings, added browser specific
classes that can be used to start a browser without the builder.

v2.34.0

Added native support for the ChromeDriver. When using the Builder,
requesting chrome without specifying a remote server URL will default to
the native ChromeDriver implementation. The
ChromeDriver server
must be downloaded separately.