2015-04-04 09:53:59 -07:00
|
|
|
// 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
|
2014-11-12 19:33:37 +00:00
|
|
|
//
|
2015-04-04 09:53:59 -07:00
|
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
2014-11-12 19:33:37 +00: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
|
|
|
|
|
// KIND, either express or implied. See the License for the
|
|
|
|
|
// specific language governing permissions and limitations
|
|
|
|
|
// under the License.
|
2013-06-23 20:19:52 -07:00
|
|
|
|
2015-02-19 13:50:30 -08:00
|
|
|
/**
|
2015-02-27 13:03:43 -08:00
|
|
|
* @fileoverview Defines a {@linkplain Driver WebDriver} client for the Chrome
|
|
|
|
|
* web browser. Before using this module, you must download the latest
|
|
|
|
|
* [ChromeDriver release] and ensure it can be found on your system [PATH].
|
2015-02-19 13:50:30 -08:00
|
|
|
*
|
|
|
|
|
* There are three primary classes exported by this module:
|
|
|
|
|
*
|
|
|
|
|
* 1. {@linkplain ServiceBuilder}: configures the
|
|
|
|
|
* {@link selenium-webdriver/remote.DriverService remote.DriverService}
|
2015-02-27 13:03:43 -08:00
|
|
|
* that manages the [ChromeDriver] child process.
|
2015-02-19 13:50:30 -08:00
|
|
|
*
|
|
|
|
|
* 2. {@linkplain Options}: defines configuration options for each new Chrome
|
|
|
|
|
* session, such as which {@linkplain Options#setProxy proxy} to use,
|
|
|
|
|
* what {@linkplain Options#addExtensions extensions} to install, or
|
|
|
|
|
* what {@linkplain Options#addArguments command-line switches} to use when
|
|
|
|
|
* starting the browser.
|
|
|
|
|
*
|
|
|
|
|
* 3. {@linkplain Driver}: the WebDriver client; each new instance will control
|
|
|
|
|
* a unique browser session with a clean user profile (unless otherwise
|
|
|
|
|
* configured through the {@link Options} class).
|
|
|
|
|
*
|
2017-07-23 11:32:38 -07:00
|
|
|
* let chrome = require('selenium-webdriver/chrome');
|
|
|
|
|
* let {Builder} = require('selenium-webdriver');
|
|
|
|
|
*
|
|
|
|
|
* let driver = new Builder()
|
|
|
|
|
* .forBrowser('chrome')
|
2023-12-15 16:45:19 -06:00
|
|
|
* .setChromeOptions(new chrome.Options())
|
2017-07-23 11:32:38 -07:00
|
|
|
* .build();
|
|
|
|
|
*
|
2015-02-27 13:03:43 -08:00
|
|
|
* __Customizing the ChromeDriver Server__ <a id="custom-server"></a>
|
2015-02-19 13:50:30 -08:00
|
|
|
*
|
|
|
|
|
* By default, every Chrome session will use a single driver service, which is
|
|
|
|
|
* started the first time a {@link Driver} instance is created and terminated
|
|
|
|
|
* when this process exits. The default service will inherit its environment
|
|
|
|
|
* from the current process and direct all output to /dev/null. You may obtain
|
|
|
|
|
* a handle to this default service using
|
|
|
|
|
* {@link #getDefaultService getDefaultService()} and change its configuration
|
|
|
|
|
* with {@link #setDefaultService setDefaultService()}.
|
|
|
|
|
*
|
|
|
|
|
* You may also create a {@link Driver} with its own driver service. This is
|
|
|
|
|
* useful if you need to capture the server's log output for a specific session:
|
|
|
|
|
*
|
2016-01-31 00:18:39 -08:00
|
|
|
* let chrome = require('selenium-webdriver/chrome');
|
2015-02-19 13:50:30 -08:00
|
|
|
*
|
2016-01-31 00:18:39 -08:00
|
|
|
* let service = new chrome.ServiceBuilder()
|
2015-02-19 13:50:30 -08:00
|
|
|
* .loggingTo('/my/log/file.txt')
|
|
|
|
|
* .enableVerboseLogging()
|
|
|
|
|
* .build();
|
|
|
|
|
*
|
2016-01-31 00:18:39 -08:00
|
|
|
* let options = new chrome.Options();
|
2015-02-19 13:50:30 -08:00
|
|
|
* // configure browser options ...
|
|
|
|
|
*
|
2017-01-30 09:19:20 -08:00
|
|
|
* let driver = chrome.Driver.createSession(options, service);
|
2015-02-19 13:50:30 -08:00
|
|
|
*
|
|
|
|
|
* Users should only instantiate the {@link Driver} class directly when they
|
|
|
|
|
* need a custom driver service configuration (as shown above). For normal
|
|
|
|
|
* operation, users should start Chrome using the
|
|
|
|
|
* {@link selenium-webdriver.Builder}.
|
2015-02-27 13:03:43 -08:00
|
|
|
*
|
|
|
|
|
* __Working with Android__ <a id="android"></a>
|
|
|
|
|
*
|
|
|
|
|
* The [ChromeDriver][android] supports running tests on the Chrome browser as
|
|
|
|
|
* well as [WebView apps][webview] starting in Android 4.4 (KitKat). In order to
|
|
|
|
|
* work with Android, you must first start the adb
|
|
|
|
|
*
|
|
|
|
|
* adb start-server
|
|
|
|
|
*
|
|
|
|
|
* By default, adb will start on port 5037. You may change this port, but this
|
|
|
|
|
* will require configuring a [custom server](#custom-server) that will connect
|
|
|
|
|
* to adb on the {@linkplain ServiceBuilder#setAdbPort correct port}:
|
|
|
|
|
*
|
2016-01-31 00:18:39 -08:00
|
|
|
* let service = new chrome.ServiceBuilder()
|
2015-02-27 13:03:43 -08:00
|
|
|
* .setAdbPort(1234)
|
|
|
|
|
* build();
|
|
|
|
|
* // etc.
|
|
|
|
|
*
|
|
|
|
|
* The ChromeDriver may be configured to launch Chrome on Android using
|
|
|
|
|
* {@link Options#androidChrome()}:
|
|
|
|
|
*
|
2016-01-31 00:18:39 -08:00
|
|
|
* let driver = new Builder()
|
2015-02-27 13:03:43 -08:00
|
|
|
* .forBrowser('chrome')
|
|
|
|
|
* .setChromeOptions(new chrome.Options().androidChrome())
|
|
|
|
|
* .build();
|
|
|
|
|
*
|
|
|
|
|
* Alternatively, you can configure the ChromeDriver to launch an app with a
|
|
|
|
|
* Chrome-WebView by setting the {@linkplain Options#androidActivity
|
|
|
|
|
* androidActivity} option:
|
|
|
|
|
*
|
2016-01-31 00:18:39 -08:00
|
|
|
* let driver = new Builder()
|
2015-02-27 13:03:43 -08:00
|
|
|
* .forBrowser('chrome')
|
|
|
|
|
* .setChromeOptions(new chrome.Options()
|
|
|
|
|
* .androidPackage('com.example')
|
|
|
|
|
* .androidActivity('com.example.Activity'))
|
|
|
|
|
* .build();
|
|
|
|
|
*
|
2015-04-08 20:09:31 -07:00
|
|
|
* [Refer to the ChromeDriver site] for more information on using the
|
2015-02-27 13:03:43 -08:00
|
|
|
* [ChromeDriver with Android][android].
|
|
|
|
|
*
|
2019-10-02 17:37:29 +01:00
|
|
|
* [ChromeDriver]: https://chromedriver.chromium.org/
|
2015-02-27 13:03:43 -08:00
|
|
|
* [ChromeDriver release]: http://chromedriver.storage.googleapis.com/index.html
|
|
|
|
|
* [PATH]: http://en.wikipedia.org/wiki/PATH_%28variable%29
|
2019-10-02 17:37:29 +01:00
|
|
|
* [android]: https://chromedriver.chromium.org/getting-started/getting-started---android
|
2015-02-27 13:03:43 -08:00
|
|
|
* [webview]: https://developer.chrome.com/multidevice/webview/overview
|
2024-05-18 16:43:02 -07:00
|
|
|
*
|
|
|
|
|
* @module selenium-webdriver/chrome
|
2015-02-19 13:50:30 -08:00
|
|
|
*/
|
|
|
|
|
|
2024-05-20 09:50:09 +02:00
|
|
|
'use strict'
|
2013-06-23 20:19:52 -07:00
|
|
|
|
2024-05-20 09:50:09 +02:00
|
|
|
const { Browser } = require('./lib/capabilities')
|
|
|
|
|
const chromium = require('./chromium')
|
|
|
|
|
const CHROME_CAPABILITY_KEY = 'goog:chromeOptions'
|
2013-06-23 20:19:52 -07:00
|
|
|
|
2020-10-23 13:15:57 +05:30
|
|
|
/** @type {remote.DriverService} */
|
2017-10-22 13:51:44 -07:00
|
|
|
|
2013-06-29 11:01:27 -07:00
|
|
|
/**
|
2015-02-27 13:03:43 -08:00
|
|
|
* Creates {@link selenium-webdriver/remote.DriverService} instances that manage
|
2019-10-02 17:37:29 +01:00
|
|
|
* a [ChromeDriver](https://chromedriver.chromium.org/)
|
2015-02-19 13:50:30 -08:00
|
|
|
* server in a child process.
|
2013-06-29 11:01:27 -07:00
|
|
|
*/
|
2020-03-04 16:38:33 +02:00
|
|
|
class ServiceBuilder extends chromium.ServiceBuilder {
|
2024-05-20 09:50:09 +02:00
|
|
|
/**
|
|
|
|
|
* @param {string=} opt_exe Path to the server executable to use. If omitted,
|
|
|
|
|
* the builder will attempt to locate the chromedriver on the current
|
|
|
|
|
* PATH. If the chromedriver is not available in path, selenium-manager will
|
|
|
|
|
* download the chromedriver
|
|
|
|
|
* @throws {Error} If provided executable does not exist, or the chromedriver
|
|
|
|
|
* cannot be found on the PATH.
|
|
|
|
|
*/
|
|
|
|
|
constructor(opt_exe) {
|
|
|
|
|
super(opt_exe)
|
|
|
|
|
}
|
2016-01-24 14:45:02 -08:00
|
|
|
}
|
2013-06-23 20:19:52 -07:00
|
|
|
|
2013-06-29 11:01:27 -07:00
|
|
|
/**
|
|
|
|
|
* Class for managing ChromeDriver specific options.
|
2013-06-23 20:19:52 -07:00
|
|
|
*/
|
2020-03-04 16:38:33 +02:00
|
|
|
class Options extends chromium.Options {
|
2024-05-20 09:50:09 +02:00
|
|
|
/**
|
|
|
|
|
* Sets the path to the Chrome binary to use. On Mac OS X, this path should
|
|
|
|
|
* reference the actual Chrome executable, not just the application binary
|
|
|
|
|
* (e.g. "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome").
|
|
|
|
|
*
|
|
|
|
|
* The binary path be absolute or relative to the chromedriver server
|
|
|
|
|
* executable, but it must exist on the machine that will launch Chrome.
|
|
|
|
|
*
|
|
|
|
|
* @param {string} path The path to the Chrome binary to use.
|
|
|
|
|
* @return {!Options} A self reference.
|
|
|
|
|
*/
|
|
|
|
|
setChromeBinaryPath(path) {
|
|
|
|
|
return this.setBinaryPath(path)
|
|
|
|
|
}
|
2015-02-27 13:03:43 -08:00
|
|
|
|
2024-05-20 09:50:09 +02:00
|
|
|
/**
|
|
|
|
|
* Configures the ChromeDriver to launch Chrome on Android via adb. This
|
|
|
|
|
* function is shorthand for
|
|
|
|
|
* {@link #androidPackage options.androidPackage('com.android.chrome')}.
|
|
|
|
|
* @return {!Options} A self reference.
|
|
|
|
|
*/
|
|
|
|
|
androidChrome() {
|
|
|
|
|
return this.androidPackage('com.android.chrome')
|
|
|
|
|
}
|
2015-02-27 13:03:43 -08:00
|
|
|
|
2024-05-20 09:50:09 +02:00
|
|
|
/**
|
|
|
|
|
* Sets the path to Chrome's log file. This path should exist on the machine
|
|
|
|
|
* that will launch Chrome.
|
|
|
|
|
* @param {string} path Path to the log file to use.
|
|
|
|
|
* @return {!Options} A self reference.
|
|
|
|
|
*/
|
|
|
|
|
setChromeLogFile(path) {
|
|
|
|
|
return this.setBrowserLogFile(path)
|
|
|
|
|
}
|
2013-06-29 11:01:27 -07:00
|
|
|
|
2024-05-20 09:50:09 +02:00
|
|
|
/**
|
|
|
|
|
* Sets the directory to store Chrome minidumps in. This option is only
|
|
|
|
|
* supported when ChromeDriver is running on Linux.
|
|
|
|
|
* @param {string} path The directory path.
|
|
|
|
|
* @return {!Options} A self reference.
|
|
|
|
|
*/
|
|
|
|
|
setChromeMinidumpPath(path) {
|
|
|
|
|
return this.setBrowserMinidumpPath(path)
|
|
|
|
|
}
|
2016-01-24 14:45:02 -08:00
|
|
|
}
|
2013-06-29 11:01:27 -07:00
|
|
|
|
2014-08-20 21:09:18 -07:00
|
|
|
/**
|
|
|
|
|
* Creates a new WebDriver client for Chrome.
|
2015-02-11 09:28:48 -08:00
|
|
|
*/
|
2020-03-04 16:38:33 +02:00
|
|
|
class Driver extends chromium.Driver {
|
2024-05-20 09:50:09 +02:00
|
|
|
/**
|
|
|
|
|
* Creates a new session with the ChromeDriver.
|
|
|
|
|
*
|
|
|
|
|
* @param {(Capabilities|Options)=} opt_config The configuration options.
|
|
|
|
|
* @param {(remote.DriverService|http.Executor)=} opt_serviceExecutor Either
|
|
|
|
|
* a DriverService to use for the remote end, or a preconfigured executor
|
|
|
|
|
* for an externally managed endpoint. If neither is provided, the
|
|
|
|
|
* {@linkplain ##getDefaultService default service} will be used by
|
|
|
|
|
* default.
|
|
|
|
|
* @return {!Driver} A new driver instance.
|
|
|
|
|
*/
|
|
|
|
|
static createSession(opt_config, opt_serviceExecutor) {
|
|
|
|
|
let caps = opt_config || new Options()
|
|
|
|
|
return /** @type {!Driver} */ (super.createSession(caps, opt_serviceExecutor, 'goog', CHROME_CAPABILITY_KEY))
|
|
|
|
|
}
|
2022-07-05 04:31:14 +05:30
|
|
|
|
2024-05-20 09:50:09 +02:00
|
|
|
/**
|
|
|
|
|
* returns new instance chrome driver service
|
|
|
|
|
* @returns {remote.DriverService}
|
|
|
|
|
*/
|
|
|
|
|
static getDefaultService() {
|
|
|
|
|
return new ServiceBuilder().build()
|
|
|
|
|
}
|
2020-10-23 13:15:57 +05:30
|
|
|
}
|
2020-03-31 10:08:34 -07:00
|
|
|
|
2024-05-20 09:50:09 +02:00
|
|
|
Options.prototype.CAPABILITY_KEY = CHROME_CAPABILITY_KEY
|
|
|
|
|
Options.prototype.BROWSER_NAME_VALUE = Browser.CHROME
|
2015-08-06 01:22:49 -07:00
|
|
|
|
2013-06-23 20:19:52 -07:00
|
|
|
// PUBLIC API
|
2021-12-01 23:51:08 +05:30
|
|
|
module.exports = {
|
2024-05-20 09:50:09 +02:00
|
|
|
Driver,
|
|
|
|
|
Options,
|
|
|
|
|
ServiceBuilder,
|
|
|
|
|
}
|
