Capabilities are options that you can use to customize and configure a ChromeDriver session. This page documents all ChromeDriver supported capabilities and how to use them. The WebDriver language APIs provides ways to pass capabilities to ChromeDriver. The exact mechanism differs by the language, but most languages use one or both of the following mechanisms:
Using the ChromeOptions classYou can create an instance ofChromeOptions , which has convenient methods for setting ChromeDriver-specific capabilities. You can then pass the ChromeOptions object into the ChromeDriver constructor:ChromeOptions options = new ChromeOptions(); options.addExtensions(new File("/path/to/extension.crx")); ChromeDriver driver = new ChromeDriver(options); Since Selenium version 3.6.0, the ChromeOptions class in Java also implements the Capabilities interface, allowing you to specify other WebDriver capabilities not specific to ChromeDriver.ChromeOptions options = new ChromeOptions(); // Add the WebDriver proxy capability. Proxy proxy = new Proxy(); proxy.setHttpProxy("myhttpproxy:3337"); options.setCapability("proxy", proxy); // Add a ChromeDriver-specific capability. options.addExtensions(new File("/path/to/extension.crx")); ChromeDriver driver = new ChromeDriver(options); Using DesiredCapabilitiesTo use
DesiredCapabilities , you need to know the name of the capability and the type of value it takes. See the full list further below.Pythoncaps = webdriver.DesiredCapabilities.CHROME.copy() caps['acceptInsecureCerts'] = True driver = webdriver.Chrome(desired_capabilities=caps) Rubycaps = Selenium::WebDriver::Remote::Capabilities.chrome( "goog:chromeOptions" => {"args" => [ "window-size=1000,800" ]}) driver = Selenium::WebDriver.for :chrome, desired_capabilities: caps Common use casesUse custom profile (also called user data directory)By default, ChromeDriver will create a new temporary profile for each session. At times you may want to set special preferences or just use a custom profile altogether. If the former, you can use the 'chrome.prefs' capability (described later below) to specify preferences that will be applied after Chrome starts. If the latter, you can use theuser-data-dir Chrome command-line switch to tell Chrome which profile to use:ChromeOptions options = new ChromeOptions(); options.addArguments("user-data-dir=/path/to/your/custom/profile"); user-data-dir switch set to some new directory. If the path doesn't exist, Chrome will create a new profile in the specified location. You can then modify the profile settings as desired, and ChromeDriver can use the profile in the future. Open chrome://version in the browser to see what profile Chrome is using.Start Chrome maximizedChromeOptions options = new ChromeOptions(); options.addArguments("start-maximized"); Using a Chrome executable in a non-standard locationChromeOptions options = new ChromeOptions(); options.setBinary("/path/to/other/chrome/binary"); Block pop-up windowsBy default, ChromeDriver configures Chrome to allow pop-up windows. If you want to block pop-ups (i.e., restore the normal Chrome behavior when it is not controlled by ChromeDriver), do the following: ChromeOptions options = new ChromeOptions(); options.setExperimentalOption("excludeSwitches", Arrays.asList("disable-popup-blocking")); Set download directoryThe following code can be used to configure Chrome to download files to a specific directory. However, there are several caveats to be aware of:
ChromeOptions options = new ChromeOptions(); Map<String, Object> prefs = new HashMap<String, Object>(); prefs.put("download.default_directory", "/directory/path"); options.setExperimentalOption("prefs", prefs); Recognized capabilitiesPlease see Selenium documentation and W3C WebDriver standard for standard capabilities accepted by ChromeDriver. Here we only list Chrome-specific capabilities.
|
Name | Type | Default | Description |
---|---|---|---|
args |
list of strings | List of command-line arguments to use when starting Chrome. Arguments with an associated value should be separated by a '=' sign (e.g., ['start-maximized', 'user-data-dir=/tmp/temp_profile']). See here for a list of Chrome arguments. | |
binary |
string | Path to the Chrome executable to use (on Mac OS X, this should be the actual binary, not just the app. e.g., '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome') | |
extensions |
list of strings | A list of Chrome extensions to install on startup. Each item in the list should be a base-64 encoded packed Chrome extension (.crx) | |
localState |
dictionary | A dictionary with each entry consisting of the name of the preference and its value. These preferences are applied to the Local State file in the user data folder. | |
prefs |
dictionary | A dictionary with each entry consisting of the name of the preference and its value. These preferences are only applied to the user profile in use. See the 'Preferences' file in Chrome's user data directory for examples. | |
detach |
boolean | false | If false, Chrome will be quit when ChromeDriver is killed, regardless of whether the session is quit. If true, Chrome will only be quit if the session is quit (or closed). Note, if true, and the session is not quit, ChromeDriver cannot clean up the temporary user data directory that the running Chrome instance is using. |
debuggerAddress |
string | An address of a Chrome debugger server to connect to, in the form of <hostname/ip:port>, e.g. '127.0.0.1:38947' | |
excludeSwitches |
list of strings | List of Chrome command line switches to exclude that ChromeDriver by default passes when starting Chrome. Do not prefix switches with --. | |
minidumpPath |
string | Directory to store Chrome minidumps . (Supported only on Linux.) | |
mobileEmulation |
dictionary | A dictionary with either a value for “deviceName,” or values for “deviceMetrics” and “userAgent.” Refer to Mobile Emulation for more information. | |
perfLoggingPrefs |
dictionary | An optional dictionary that specifies performance logging preferences. See below for more information. | |
windowTypes | list of strings | A list of window types that will appear in the list of window handles. For access to <webview> elements, include "webview" in this list. |
perfLoggingPrefs
object
The perfLoggingPrefs dictionary has the following format (all keys are optional):
Name | Type | Default | Description |
---|---|---|---|
enableNetwork |
boolean | true | Whether or not to collect events from Network domain. |
enablePage |
boolean | true | Whether or not to collect events from Page domain. |
traceCategories |
string | (empty) | A comma-separated string of Chrome tracing categories for which trace events should be collected. An unspecified or empty string disables tracing. |
bufferUsageReportingInterval |
positive integer | 1000 | The requested number of milliseconds between DevTools trace buffer usage events. For example, if 1000, then once per second, DevTools will report how full the trace buffer is. If a report indicates the buffer usage is 100%, a warning will be issued. |
Returned Capabilities
This is a list of all the Chrome-specific returned capabilities. (i.e., what ChromeDriver returns when you create a new session)