2013-02-16 16:30:35 -08:00
|
|
|
|
# selenium-webdriver
|
|
|
|
|
|
|
2015-02-25 22:55:03 -08:00
|
|
|
|
Selenium is a browser automation library. Most often used for testing
|
|
|
|
|
|
web-applications, Selenium may be used for any task that requires automating
|
|
|
|
|
|
interaction with the browser.
|
|
|
|
|
|
|
2013-06-29 22:59:48 -07:00
|
|
|
|
## Installation
|
|
|
|
|
|
|
2016-01-15 17:20:50 -08:00
|
|
|
|
Selenium may be installed via npm with
|
2013-06-29 22:59:48 -07:00
|
|
|
|
|
|
|
|
|
|
npm install selenium-webdriver
|
|
|
|
|
|
|
2016-06-15 11:21:51 -07:00
|
|
|
|
You will need to download additional components to work with each of the major
|
2017-10-02 21:00:12 -04:00
|
|
|
|
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
|
2024-03-08 12:13:00 +00:00
|
|
|
|
[PATH]. Apple's safaridriver (v10 and above) can be found at the
|
|
|
|
|
|
following path – /usr/bin/safaridriver. To enable automation on safari,
|
2022-09-01 21:38:03 +05:30
|
|
|
|
you need to run command `safaridriver --enable`.
|
2016-06-15 11:21:51 -07:00
|
|
|
|
|
2024-03-08 12:13:00 +00:00
|
|
|
|
| Browser | Component |
|
2024-05-15 07:06:20 -07:00
|
|
|
|
| :---------------- | :------------------------------- |
|
2024-03-08 12:13:00 +00:00
|
|
|
|
| Chrome | [chromedriver(.exe)][chrome] |
|
|
|
|
|
|
| Internet Explorer | [IEDriverServer.exe][release] |
|
|
|
|
|
|
| Edge | [MicrosoftWebDriver.msi][edge] |
|
|
|
|
|
|
| Firefox | [geckodriver(.exe)][geckodriver] |
|
|
|
|
|
|
| Opera | [operadriver(.exe)][operadriver] |
|
|
|
|
|
|
| Safari | [safaridriver] |
|
2013-06-29 22:59:48 -07:00
|
|
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
2015-02-25 22:55:03 -08:00
|
|
|
|
The sample below and others are included in the `example` directory. You may
|
|
|
|
|
|
also find the tests for selenium-webdriver informative.
|
2013-06-29 22:59:48 -07:00
|
|
|
|
|
2018-01-18 23:31:33 +00:00
|
|
|
|
```javascript
|
2024-01-10 12:00:37 +00:00
|
|
|
|
const { Builder, Browser, By, Key, until } = require('selenium-webdriver')
|
2018-01-18 23:31:33 +00:00
|
|
|
|
|
2024-05-15 07:06:20 -07:00
|
|
|
|
;(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)
|
|
|
|
|
|
} finally {
|
|
|
|
|
|
await driver.quit()
|
|
|
|
|
|
}
|
2024-01-10 12:00:37 +00:00
|
|
|
|
})()
|
2018-01-18 23:31:33 +00:00
|
|
|
|
```
|
2013-02-16 16:30:35 -08:00
|
|
|
|
|
2015-02-25 22:55:03 -08:00
|
|
|
|
### Using the Builder API
|
|
|
|
|
|
|
|
|
|
|
|
The `Builder` class is your one-stop shop for configuring new WebDriver
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
2018-01-18 23:31:33 +00:00
|
|
|
|
```javascript
|
2024-01-10 12:00:37 +00:00
|
|
|
|
const webdriver = require('selenium-webdriver')
|
|
|
|
|
|
const chrome = require('selenium-webdriver/chrome')
|
|
|
|
|
|
const firefox = require('selenium-webdriver/firefox')
|
2015-02-25 22:55:03 -08:00
|
|
|
|
|
2018-01-18 23:31:33 +00:00
|
|
|
|
let driver = new webdriver.Builder()
|
2024-05-15 07:06:20 -07:00
|
|
|
|
.forBrowser(webdriver.Browser.FIREFOX)
|
|
|
|
|
|
.setChromeOptions(/* ... */)
|
|
|
|
|
|
.setFirefoxOptions(/* ... */)
|
|
|
|
|
|
.build()
|
2018-01-18 23:31:33 +00:00
|
|
|
|
```
|
2015-02-25 22:55:03 -08:00
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
|
browser at runtime through the `SELENIUM_BROWSER` environment variable. For
|
|
|
|
|
|
example, the `example/google_search.js` script is configured to run against
|
|
|
|
|
|
Firefox. You can run the example against other browsers just by changing the
|
|
|
|
|
|
runtime environment
|
|
|
|
|
|
|
|
|
|
|
|
# cd node_modules/selenium-webdriver
|
|
|
|
|
|
node example/google_search
|
|
|
|
|
|
SELENIUM_BROWSER=chrome node example/google_search
|
|
|
|
|
|
SELENIUM_BROWSER=safari node example/google_search
|
|
|
|
|
|
|
|
|
|
|
|
### The Standalone Selenium Server
|
|
|
|
|
|
|
|
|
|
|
|
The standalone Selenium Server acts as a proxy between your script and the
|
|
|
|
|
|
browser-specific drivers. The server may be used when running locally, but it's
|
|
|
|
|
|
not recommend as it introduces an extra hop for each request and will slow
|
|
|
|
|
|
things down. The server is required, however, to use a browser on a remote host
|
|
|
|
|
|
(most browser drivers, like the IEDriverServer, do not accept remote
|
|
|
|
|
|
connections).
|
|
|
|
|
|
|
|
|
|
|
|
To use the Selenium Server, you will need to install the
|
|
|
|
|
|
[JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html) and
|
|
|
|
|
|
download the latest server from [Selenium][release]. Once downloaded, run the
|
|
|
|
|
|
server with
|
|
|
|
|
|
|
2025-01-13 16:23:31 +05:30
|
|
|
|
java -jar selenium-server-4.27.0.jar standalone
|
2015-02-25 22:55:03 -08:00
|
|
|
|
|
|
|
|
|
|
You may configure your tests to run against a remote server through the Builder
|
|
|
|
|
|
API:
|
|
|
|
|
|
|
2018-01-18 23:31:33 +00:00
|
|
|
|
```javascript
|
|
|
|
|
|
let driver = new webdriver.Builder()
|
2024-05-15 07:06:20 -07:00
|
|
|
|
.forBrowser(webdriver.Browser.FIREFOX)
|
|
|
|
|
|
.usingServer('http://localhost:4444/wd/hub')
|
|
|
|
|
|
.build()
|
2018-01-18 23:31:33 +00:00
|
|
|
|
```
|
2024-03-08 12:13:00 +00:00
|
|
|
|
|
2015-02-25 22:55:03 -08:00
|
|
|
|
Or change the Builder's configuration at runtime with the `SELENIUM_REMOTE_URL`
|
|
|
|
|
|
environment variable:
|
|
|
|
|
|
|
|
|
|
|
|
SELENIUM_REMOTE_URL="http://localhost:4444/wd/hub" node script.js
|
|
|
|
|
|
|
|
|
|
|
|
You can experiment with these options using the `example/google_search.js`
|
|
|
|
|
|
script provided with `selenium-webdriver`.
|
|
|
|
|
|
|
2013-02-16 16:30:35 -08:00
|
|
|
|
## Documentation
|
|
|
|
|
|
|
2016-01-15 11:44:28 -08:00
|
|
|
|
API documentation is available online from the [Selenium project][api].
|
2016-04-11 11:39:58 -07:00
|
|
|
|
Additional resources include
|
2015-02-25 22:55:03 -08:00
|
|
|
|
|
2025-05-06 13:35:06 -04:00
|
|
|
|
- the #selenium channel on Libera IRC
|
2015-02-25 22:55:03 -08:00
|
|
|
|
- the [selenium-users@googlegroups.com][users] list
|
2019-11-16 21:28:00 +01:00
|
|
|
|
- [SeleniumHQ](https://selenium.dev/documentation/) documentation
|
2015-02-25 22:55:03 -08:00
|
|
|
|
|
|
|
|
|
|
## Contributing
|
|
|
|
|
|
|
|
|
|
|
|
Contributions are accepted either through [GitHub][gh] pull requests or patches
|
2019-11-23 19:36:01 +01:00
|
|
|
|
via the [Selenium issue tracker][issues].
|
2013-02-16 16:30:35 -08:00
|
|
|
|
|
2016-01-15 17:15:50 -08:00
|
|
|
|
## Node Support Policy
|
|
|
|
|
|
|
|
|
|
|
|
Each version of selenium-webdriver will support the latest _semver-minor_
|
|
|
|
|
|
version of the [LTS] and stable Node releases. All _semver-major_ &
|
|
|
|
|
|
_semver-minor_ versions between the LTS and stable release will have "best
|
|
|
|
|
|
effort" support. Following a Selenium release, any _semver-minor_ Node releases
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
2025-01-13 16:23:31 +05:30
|
|
|
|
For example, suppose the current LTS and stable releases are v22.13.0 and
|
|
|
|
|
|
v23.6.0,
|
2016-01-15 17:15:50 -08:00
|
|
|
|
respectively. Then a Selenium release would have the following support levels:
|
|
|
|
|
|
|
2025-01-13 16:23:31 +05:30
|
|
|
|
| Version | Support |
|
|
|
|
|
|
| :--------: | :-----------: |
|
|
|
|
|
|
| <= 16.20.2 | _unsupported_ |
|
|
|
|
|
|
| 16.20.2 | supported |
|
|
|
|
|
|
| 18.8.0 | supported |
|
|
|
|
|
|
| >= 22.13.0 | best effort |
|
|
|
|
|
|
| v.Next | _unsupported_ |
|
2016-01-15 17:15:50 -08:00
|
|
|
|
|
|
|
|
|
|
### Support Level Definitions
|
|
|
|
|
|
|
|
|
|
|
|
- _supported:_ A selenium-webdriver release will be API compatible with the
|
2024-03-08 12:13:00 +00:00
|
|
|
|
platform API, without the use of runtime flags.
|
2016-01-15 17:15:50 -08:00
|
|
|
|
|
|
|
|
|
|
- _best effort:_ Bugs will be investigated as time permits. API compatibility is
|
2024-03-08 12:13:00 +00:00
|
|
|
|
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.
|
2016-01-15 17:15:50 -08:00
|
|
|
|
|
|
|
|
|
|
- _unsupported:_ Bug submissions will be closed as will-not-fix and API
|
2024-03-08 12:13:00 +00:00
|
|
|
|
compatibility is not guaranteed.
|
2016-01-15 17:15:50 -08:00
|
|
|
|
|
|
|
|
|
|
### 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:
|
|
|
|
|
|
|
2024-03-08 12:13:00 +00:00
|
|
|
|
| Release | Status | END-OF-LIFE |
|
2024-05-15 07:06:20 -07:00
|
|
|
|
| :-----: | :-------------: | :---------: |
|
2025-01-13 16:23:31 +05:30
|
|
|
|
| v18.x | Maintenance LTS | 2025-04-30 |
|
|
|
|
|
|
| v19.x | End-of-Life | 2023-06-01 |
|
|
|
|
|
|
| v20.x | Maintenance LTS | 2026-04-30 |
|
|
|
|
|
|
| v21.x | End-of-Life | 2024-06-01 |
|
|
|
|
|
|
| V22.x | Active LTS | 2027-04-30 |
|
|
|
|
|
|
| V23.x | Current | 2025-06-01 |
|
2016-01-15 17:15:50 -08:00
|
|
|
|
|
2013-02-16 16:30:35 -08:00
|
|
|
|
## Issues
|
|
|
|
|
|
|
2015-02-25 22:55:03 -08:00
|
|
|
|
Please report any issues using the [Selenium issue tracker][issues]. When using
|
|
|
|
|
|
the issue tracker
|
|
|
|
|
|
|
2024-01-10 12:00:37 +00:00
|
|
|
|
- **Do** include a detailed description of the problem.
|
|
|
|
|
|
- **Do** include a link to a [gist](http://gist.github.com/) with any
|
2024-03-08 12:13:00 +00:00
|
|
|
|
interesting stack traces/logs (you may also attach these directly to the bug
|
|
|
|
|
|
report).
|
2024-01-10 12:00:37 +00:00
|
|
|
|
- **Do** include a [reduced test case][reduction]. Reporting "unable to find
|
2024-03-08 12:13:00 +00:00
|
|
|
|
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.
|
2024-01-10 12:00:37 +00:00
|
|
|
|
- **Do not** use the issue tracker to submit basic help requests. All help
|
2024-03-08 12:13:00 +00:00
|
|
|
|
inquiries should be directed to the [user forum][users] or #selenium IRC
|
|
|
|
|
|
channel.
|
2024-01-10 12:00:37 +00:00
|
|
|
|
- **Do not** post empty "I see this too" or "Any updates?" comments. These
|
2024-03-08 12:13:00 +00:00
|
|
|
|
provide no additional information and clutter the log.
|
2024-01-10 12:00:37 +00:00
|
|
|
|
- **Do not** report regressions on closed bugs as they are not actively
|
2024-03-08 12:13:00 +00:00
|
|
|
|
monitored for updates (especially bugs that are >6 months old). Please open a
|
|
|
|
|
|
new issue and reference the original bug in your report.
|
2013-02-16 16:30:35 -08:00
|
|
|
|
|
|
|
|
|
|
## License
|
|
|
|
|
|
|
2015-04-04 09:53:59 -07:00
|
|
|
|
Licensed to the Software Freedom Conservancy (SFC) under one
|
2024-03-08 12:13:00 +00:00
|
|
|
|
or more contributor license agreements. See the NOTICE file
|
2015-04-04 09:53:59 -07:00
|
|
|
|
distributed with this work for additional information
|
2024-03-08 12:13:00 +00:00
|
|
|
|
regarding copyright ownership. The SFC licenses this file
|
2015-04-04 09:53:59 -07:00
|
|
|
|
to you under the Apache License, Version 2.0 (the
|
|
|
|
|
|
"License"); you may not use this file except in compliance
|
2024-03-08 12:13:00 +00:00
|
|
|
|
with the License. You may obtain a copy of the License at
|
2014-02-09 12:48:07 -08:00
|
|
|
|
|
2015-02-25 22:55:03 -08:00
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
2014-02-09 12:48:07 -08:00
|
|
|
|
|
2015-04-04 09:53:59 -07:00
|
|
|
|
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
|
2024-03-08 12:13:00 +00:00
|
|
|
|
KIND, either express or implied. See the License for the
|
2015-04-04 09:53:59 -07:00
|
|
|
|
specific language governing permissions and limitations
|
|
|
|
|
|
under the License.
|
2015-02-25 22:55:03 -08:00
|
|
|
|
|
2016-01-15 17:15:50 -08:00
|
|
|
|
[LTS]: https://github.com/nodejs/LTS
|
2016-06-15 11:21:51 -07:00
|
|
|
|
[PATH]: http://en.wikipedia.org/wiki/PATH_%28variable%29
|
2024-06-14 17:08:25 +03:00
|
|
|
|
[api]: https://www.selenium.dev/selenium/docs/api/javascript/
|
2024-05-14 21:30:38 -07:00
|
|
|
|
[chrome]: https://googlechromelabs.github.io/chrome-for-testing/#stable
|
2015-02-25 22:55:03 -08:00
|
|
|
|
[gh]: https://github.com/SeleniumHQ/selenium/
|
2015-03-12 18:29:47 -07:00
|
|
|
|
[issues]: https://github.com/SeleniumHQ/selenium/issues
|
2016-01-07 16:52:18 -08:00
|
|
|
|
[edge]: http://go.microsoft.com/fwlink/?LinkId=619687
|
2016-06-15 11:21:51 -07:00
|
|
|
|
[geckodriver]: https://github.com/mozilla/geckodriver/releases/
|
2015-02-25 22:55:03 -08:00
|
|
|
|
[reduction]: http://www.webkit.org/quality/reduction.html
|
2021-08-20 17:32:30 +02:00
|
|
|
|
[release]: https://www.selenium.dev/downloads/
|
2015-04-04 09:53:59 -07:00
|
|
|
|
[users]: https://groups.google.com/forum/#!forum/selenium-users
|
2016-08-30 02:41:27 +10:00
|
|
|
|
[safaridriver]: https://developer.apple.com/library/prerelease/content/releasenotes/General/WhatsNewInSafari/Articles/Safari_10_0.html#//apple_ref/doc/uid/TP40014305-CH11-DontLinkElementID_28
|
2021-08-20 17:32:30 +02:00
|
|
|
|
[operadriver]: https://github.com/operasoftware/operachromiumdriver/releases
|
