diff options
Diffstat (limited to 'node_modules/selenium-webdriver/README.md')
| -rw-r--r-- | node_modules/selenium-webdriver/README.md | 239 |
1 files changed, 239 insertions, 0 deletions
diff --git a/node_modules/selenium-webdriver/README.md b/node_modules/selenium-webdriver/README.md new file mode 100644 index 000000000..0b70aeddc --- /dev/null +++ b/node_modules/selenium-webdriver/README.md @@ -0,0 +1,239 @@ +# selenium-webdriver + +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. + +## Installation + +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, Safari, 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 in macOS Sierra. You will need to enable Remote Automation in +the Develop menu of Safari 10 before testing. + +> **NOTE:** Mozilla's [geckodriver] is only required for Firefox 47+. +> Everything you need for Firefox 38-46 is included with this package. + +> **NOTE:** Apple's [safaridriver] is preferred for testing Safari 10+. +> To test versions of Safari prior to Safari 10, The +> [SafariDriver.safariextz][release] browser extension should be +> installed in your browser before using Selenium. We recommend +> disabling the extension when using the browser without Selenium +> or installing the extension in a profile only used for testing. + + +| Browser | Component | +| ----------------- | ---------------------------------- | +| Chrome | [chromedriver(.exe)][chrome] | +| Internet Explorer | [IEDriverServer.exe][release] | +| Edge | [MicrosoftWebDriver.msi][edge] | +| Firefox 47+ | [geckodriver(.exe)][geckodriver] | +| PhantomJS | [phantomjs(.exe)][phantomjs] | +| Opera | [operadriver(.exe)][opera] | +| Safari | [safaridriver] | + +## Usage + +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(); + +### 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: + + var webdriver = require('selenium-webdriver'), + chrome = require('selenium-webdriver/chrome'), + firefox = require('selenium-webdriver/firefox'); + + var 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 +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 + + java -jar selenium-server-standalone-2.45.0.jar + +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(); + +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`. + +## Documentation + +API documentation is available online from the [Selenium project][api]. +Additional resources include + +- the #selenium channel on freenode IRC +- the [selenium-users@googlegroups.com][users] list +- [SeleniumHQ](http://www.seleniumhq.org/docs/) documentation + +## Contributing + +Contributions are accepted either through [GitHub][gh] pull requests or patches +via the [Selenium issue tracker][issues]. You must sign our +[Contributor License Agreement][cla] before your changes will be accepted. + +## 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. + +For example, suppose the current LTS and stable releases are v4.2.4 and v5.4.1, +respectively. Then a Selenium release would have the following support levels: + +| Version | Support | +| ------- | ------------- | +| <= 4.1 | _unsupported_ | +| 4.2 | supported | +| 5.0-3 | best effort | +| 5.4 | supported | +| >= 5.5 | 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. + +- _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. + +- _unsupported:_ Bug submissions will be closed as will-not-fix and API + 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: + +| Date | LTS | Stable | +| --------- | ---: | -----: | +| (current) | 4.2 | 5.0 | +| 2016-04 | 4.2 | 6.0 | +| 2016-10 | 6.0 | 7.0 | +| 2017-04 | 6.0 | 8.0 | +| 2017-10 | 8.0 | 9.0 | + +## 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 upates (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 +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. + +[LTS]: https://github.com/nodejs/LTS +[PATH]: http://en.wikipedia.org/wiki/PATH_%28variable%29 +[api]: http://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/ +[cla]: http://goo.gl/qC50R +[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 +[release]: http://selenium-release.storage.googleapis.com/index.html +[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 |