Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Clear out junk files and repair common Windows errorsFree Scan →Selenium 4 capabilities are name-and-value settings sent when WebDriver creates a browser session. Set them through the browser’s Options class—such as ChromeOptions or FirefoxOptions—and pass that object to a local driver or RemoteWebDriver. Use standard W3C capability names for portable settings; put cloud-provider-specific settings in the namespace and structure that provider documents.
What Selenium 4 capabilities do
A capability describes a condition or behavior requested for a WebDriver session: for example, the browser, its version, whether it should accept insecure certificates, or how navigation waits for a page to load. The new-session request is where those settings are applied. The browser Options object is Selenium’s supported way to express them in Selenium 4; the Selenium Project says, “As of Selenium 4, you must use the browser options classes.” See Selenium’s Browser Options documentation.
As an Amazon Associate I earn from qualifying purchases.
Options also carry browser-specific configuration, so they are more than a bag of generic settings. For a remote session, an Options instance is required because it identifies which browser the remote end should provide.
Free tools Windows power users keep installed
One-click scans. No signup required.
Choose the right kind of setting
Keep four categories distinct. A setting’s name and namespace determine whether it is portable and which system must understand it.
#1 Best Overall
| Category | Examples | Where it applies |
|---|---|---|
| Standard W3C capabilities | browserName, browserVersion, platformName, pageLoadStrategy |
Shared WebDriver session settings. Selenium 4 uses the W3C WebDriver standard and no longer supports the legacy protocol. See Upgrade to Selenium 4. |
| Browser-specific options | Browser-specific command-line arguments, preferences, or other options | Only the browser and binding that document the option. Use the appropriate browser Options class. |
| Selenium Grid settings and metadata | se:name, se:downloadsEnabled, custom matching keys |
Selenium Grid nodes and sessions, when configured to support them. See Grid getting started and Grid CLI options. |
| Cloud-provider settings | Provider-defined keys such as cloud:options |
The named provider’s remote service, not Selenium universally. Follow that provider’s current instructions. |
Standard capabilities worth knowing
Selenium’s upgrade guide lists the following standard names. Options classes typically set browserName for you; choose the others only when the session needs them.
| Capability | What it controls | Practical note |
|---|---|---|
browserName |
Browser requested for the session. | Usually comes from the browser Options class. |
browserVersion |
Requested browser version. | Most useful when a remote end offers multiple versions. Selenium notes that recent Selenium Manager versions can automatically download a browser version missing locally, subject to the environment and current implementation. |
platformName |
Requested operating system or platform. | Remote services can use it to select a platform. It replaces the legacy name platform. |
acceptInsecureCerts |
Whether the session may trust insecure certificates. | Use only where accepting such certificates is appropriate for the test. |
pageLoadStrategy |
How far a navigation waits for document readiness. | See the strategy comparison below; this does not establish that a dynamic app’s data is ready. |
timeouts |
Script, page-load, and implicit element-location wait limits. | Set timeouts to suit the operations and application under test. |
unhandledPromptBehavior |
What to do with an unexpected browser prompt. | The documented default is dismiss and notify. |
proxy |
Proxy settings for browser traffic. | Can route traffic through a proxy; it is not by itself a complete traffic-capture or mocking solution. |
Set page-load behavior deliberately
| Strategy | Navigation waits for | When to consider it |
|---|---|---|
normal (default) |
Document readiness state complete. |
Use when the test expects the normal document-load wait. |
eager |
Document readiness state interactive. |
May allow the test to proceed before all subresources finish; it must still wait for the elements or data it needs. |
none |
No page-readiness condition. | The test takes responsibility for waiting before interacting. |
A completed document load is not proof that a JavaScript-heavy single-page application has finished rendering or fetching data. Whichever strategy you choose, wait explicitly for the application state your next step depends on. A faster return from navigation without that wait can make tests flaky rather than faster in a useful way.
Timeouts are separate controls
Selenium’s Options documentation reports defaults of 30,000 ms for the script timeout, 300,000 ms for the page-load timeout, and 0 ms for the implicit element-location wait. These values govern different operations: asynchronous script execution, navigation, and element lookup respectively. The documented default for unhandledPromptBehavior is dismiss and notify. Do not treat one timeout as a universal wait for the entire test; use condition-based waits where the application must reach a particular state.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallRank #2
Configure a local browser session
The following Python example uses Selenium’s Options and Service APIs with Chrome. Install Selenium and have Chrome available in the environment; Selenium Manager may configure a driver when enabled. Verify API details against the current documentation for your Selenium release.
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.chrome.service import Service
options = Options()
options.page_load_strategy = "eager"
options.accept_insecure_certs = True
# A local Chrome session. Service can be configured with a driver path
# or other service settings when your environment requires them.
driver = webdriver.Chrome(service=Service(), options=options)
try:
driver.set_page_load_timeout(45)
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()For a local session, omit settings you do not need. The browser Options class supplies the browser identity; session behavior can also be configured through driver methods such as set_page_load_timeout. Check the current binding documentation for exact APIs in your language and Selenium version.
Use RemoteWebDriver and Selenium Grid
A remote session needs both a browser Options instance and the remote endpoint. This Python example requests Chrome on a Grid at the URL shown in Selenium’s getting-started flow:
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
options.set_capability("se:name", "checkout test")
driver = webdriver.Remote(
command_executor="http://localhost:4444",
options=options,
)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()Start and configure Grid according to the Grid guide; the quick-start prerequisites include Java 11+, browser(s), and browser drivers, with Selenium Manager able to configure drivers when enabled. For a custom matching capability, configure the relevant nodes to advertise the corresponding stereotype or metadata and include that capability in each session request. A request cannot route to a node that does not match it.
Managed downloads need both sides configured
Grid’s managed-download example requires a node configured for managed downloads and the session capability se:downloadsEnabled. Adding that capability to the request alone does not configure the node. Consult the current Grid CLI options for the matching node setting and syntax.
Use provider-specific settings without breaking portability
Capabilities outside the standard list need a vendor prefix. Selenium’s upgrade guide illustrates provider-specific build and name values inside cloud:options. The exact prefix, object shape, and accepted values belong to the provider. Do not send an unprefixed custom key and assume Selenium or another provider will interpret it; check the current provider instructions before constructing the Options object.
Migrate legacy Desired Capabilities
“Desired Capabilities” is a legacy term often seen in older examples. In Selenium 4, build configuration with the browser Options class and use W3C names. The upgrade guide identifies browserVersion as the replacement for version, and platformName as the replacement for platform. It also documents language-binding changes: Python’s deprecated executable_path driver construction moves to a Service object, and C# replaces AddAdditionalCapability with AddAdditionalOption. Match migration details to the binding and Selenium version you use.
Troubleshoot capability and session errors
- Session cannot be created or browser is not selected: pass the browser’s Options instance to the driver, especially for RemoteWebDriver. For local execution, verify that the browser is available and that the environment can configure its driver.
- Remote session cannot find a matching node: compare requested browser, version, platform, and custom keys with what the Grid nodes advertise. Configure the key on every relevant node and include it in each request that needs that match.
- A cloud option is rejected or ignored: make sure the key is vendor-prefixed and nested exactly as the provider requires. Provider-specific keys are not portable standard capabilities.
- Navigation returns before the page is usable: with
eagerornone, wait explicitly for the required element or application state. Evennormaldoes not guarantee a single-page application’s dynamic content is ready. - Navigation or script times out: identify which operation timed out, then adjust its corresponding timeout or investigate the page or script. Raising an unrelated timeout will not address the cause.
- Unexpected prompt interrupts a test: review
unhandledPromptBehaviorand handle expected alerts explicitly; the documented default dismisses and notifies. - Legacy examples fail: replace direct Desired Capabilities patterns and obsolete names with the Options class and current standard names for your binding.
Or skip the browser setup
If your goal is a website screenshot rather than a browser automation session, ScreenshotNeo offers a one-call screenshot API. For example, use cURL to save a WebP capture (see the API documentation):
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_pdf tools for AI agents. The free plan includes 1,000 screenshots a month without a card; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan.
Frequently Asked Questions
Can I set capabilities after creating a WebDriver session?
Capabilities describe the requested session at creation. They are not a general mechanism for changing the session’s browser or platform after it has started.
Are browser Options settings identical across Chrome and Firefox?
No. Selenium provides shared W3C settings, but each browser can define additional options that should be treated as browser-specific.
Does Selenium Grid guarantee the exact browser version I request?
A version request can only be satisfied when the remote environment offers a matching browser or can obtain one under its configuration. Check the Grid or provider’s available versions.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
