How to Use Desired Capabilities in Selenium
Learn how Selenium 4 uses browser Options to configure capabilities, including remote sessions, page-load strategies, migration, and common fixes.
In Selenium 4, configure session capabilities with the browser’s Options class and pass that object to the driver. For example, use ChromeOptions for Chrome or FirefoxOptions for Firefox. The older DesiredCapabilities-centered pattern belongs to Selenium 3-era code; use Options for new Selenium 4 sessions, especially remote sessions.
Capabilities describe the browser and features requested when a WebDriver session starts. They matter most with Remote WebDriver or Selenium Grid, where the remote end must find a browser that matches the request. Selenium’s Browser Options documentation and Selenium 4 migration guide describe the current pattern and standard capability names.
1. Set capabilities with browser Options
For a local browser, create the matching Options object, set any desired capability values, and give it to the driver. Install Selenium and the browser driver using the setup instructions for your environment before running the examples.
Python: local Chrome
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
options.set_capability("acceptInsecureCerts", True)
options.page_load_strategy = "eager"
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()Python: remote Firefox
For a remote session, pass an Options instance to webdriver.Remote. Replace the example endpoint and requested browser version with values supported by your Grid or cloud provider. The endpoint below is a placeholder; it is not a public service.
from selenium import webdriver
from selenium.webdriver.firefox.options import Options
options = Options()
options.set_capability("platformName", "windows")
options.browser_version = "142"
# Replace this placeholder with your Selenium Grid or provider endpoint.
driver = webdriver.Remote(
command_executor="http://grid.example:4444/wd/hub",
options=options,
)
try:
driver.get("https://example.com")
print(driver.title)
finally:
driver.quit()The Python Remote WebDriver API documents this Options-based form. See the Python capabilities API reference for the current API details.
Java: local Chrome
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.chrome.ChromeOptions;
public class CapabilitiesExample {
public static void main(String[] args) {
ChromeOptions options = new ChromeOptions();
options.setCapability("acceptInsecureCerts", true);
options.setPageLoadStrategy(org.openqa.selenium.PageLoadStrategy.EAGER);
WebDriver driver = new ChromeDriver(options);
try {
driver.get("https://example.com");
System.out.println(driver.getTitle());
} finally {
driver.quit();
}
}
}Use the equivalent browser Options class when selecting Firefox, Edge, Safari, or another supported browser. The requested browser must be installed locally for a local session, or available on the remote Grid for a remote session.
2. What capabilities do
A new WebDriver session starts with a request describing the browser and configuration. The remote end either creates a session that satisfies the request or rejects it. In the W3C WebDriver model, alwaysMatch describes required features; if the remote end cannot provide them, session creation fails. firstMatch can describe alternatives considered in order. See MDN’s WebDriver capabilities reference.
In ordinary Selenium code, use the browser Options API rather than manually constructing a W3C capabilities payload. Options holds the browser selection and capability values in the form Selenium expects. It also identifies the requested browser for remote sessions.
Common standard capabilities
| Capability | What it requests | Notes |
|---|---|---|
browserName |
Browser family | Usually set by the browser-specific Options class. |
browserVersion |
Browser version | Use this standard spelling in Selenium 4. |
platformName |
Operating-system platform | Use this standard spelling in Selenium 4. |
acceptInsecureCerts |
Whether the session may accept insecure TLS certificates | Set it only when that behavior is appropriate for your test. |
pageLoadStrategy |
When navigation returns control to the test | See the strategy table below. |
proxy |
Proxy configuration | Use the Selenium API or the format expected by your remote end. |
timeouts |
Session timeout values | Configure through Selenium’s timeout APIs where possible. |
unhandledPromptBehavior |
How unexpected browser prompts are handled | Confirm behavior against the browser and driver in use. |
The Selenium 4 migration guide identifies browserVersion and platformName as replacements for the legacy names version and platform. Use the standard W3C spellings in new configurations.
3. Choose a page-load strategy
| Strategy | Navigation returns when | Tradeoff |
|---|---|---|
normal (default) |
The document ready state is complete and resources have downloaded. |
Often waits longer for images and other resources. |
eager |
The document ready state is interactive. |
The DOM is ready, but resources such as images may still be loading. |
none |
WebDriver does not wait for page loading to finish. | Returns control sooner, but the test must handle readiness itself. |
These strategies affect navigation for the whole session. A faster return does not mean a JavaScript-heavy single-page application has finished rendering its dynamic content. Use explicit waits for the element or state the test actually needs.
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.common.by import By
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.support.ui import WebDriverWait
options = Options()
options.page_load_strategy = "eager"
driver = webdriver.Chrome(options=options)
try:
driver.get("https://example.com")
heading = WebDriverWait(driver, 10).until(
EC.visibility_of_element_located((By.TAG_NAME, "h1"))
)
print(heading.text)
finally:
driver.quit()4. Configure remote Grid and provider options
Remote session requests include standard capabilities and may include browser- or provider-specific extensions. Extensions need the namespace and structure expected by the Grid or cloud provider. Selenium’s migration guide shows provider settings nested under a namespaced key such as cloud:options; the namespace and accepted fields vary by provider, so check that provider’s current documentation.
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
options.browser_version = "stable"
options.set_capability("platformName", "linux")
# Example shape only. Replace the namespace and fields with the
# exact extension format documented by your provider.
options.set_capability("vendor:options", {
"build": "nightly",
"name": "checkout flow",
})
driver = webdriver.Remote(
command_executor="https://grid.example/wd/hub",
options=options,
)
try:
driver.get("https://example.com")
finally:
driver.quit()The endpoint and vendor:options block are illustrative placeholders. Do not send guessed extension keys to a real provider. A non-standard field in the wrong namespace or structure can cause session negotiation to fail.
5. Migrate Selenium 3 DesiredCapabilities code
If older code builds a DesiredCapabilities object and passes it to a driver, move the configuration to the matching Options class. Selenium’s documentation distinguishes the Selenium 3-era Desired Capabilities classes from the Selenium 4 Options pattern.
| Legacy pattern or name | Selenium 4 approach |
|---|---|
DesiredCapabilities.chrome() |
ChromeOptions() / new ChromeOptions() |
DesiredCapabilities.firefox() |
FirefoxOptions() / new FirefoxOptions() |
version |
browserVersion |
platform |
platformName |
| Remote driver given only a generic capabilities map | Pass the selected browser’s Options object to Remote WebDriver. |
Keep provider-specific settings only after checking the provider’s current extension namespace. The upgrade guide has the official migration details: Upgrade to Selenium 4.
6. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Session creation fails with an unsupported capability error | A legacy name, misspelled standard capability, or unprefixed extension was sent. | Use W3C names such as browserVersion and platformName; put extensions under the namespace required by the provider. |
| Remote session cannot find a matching browser | The requested browser, version, or platform is unavailable on the Grid. | Check the Grid’s supported browser matrix and request an installed version and platform. |
| Remote session rejects provider settings | The extension key or nested fields do not match that provider’s schema. | Compare the payload with the provider’s current documentation and remove unsupported fields. |
| Navigation returns but elements are missing | eager or none returned before later assets or application-rendered content was ready. |
Wait explicitly for the required element or application state; do not treat page-load strategy as a dynamic-content wait. |
| Local driver does not start | The browser/driver setup is missing, incompatible, or not discoverable. | Install a supported browser and driver setup for your Selenium version, then verify the local browser can launch without custom capabilities. |
| Capabilities appear ignored | A browser-specific feature was set in a generic or incorrect Options object, or the remote provider does not support it. | Use the matching browser Options class and confirm support with the remote endpoint. |
7. Performance, reliability, and cost considerations
- Page-load waits:
eagerandnonecan reduce time spent waiting for nonessential resources, but require deliberate explicit waits for application readiness. Faster navigation return can otherwise create flaky tests. - Remote matching: Request only the browser version, platform, and features the test needs. Each required capability can narrow the set of Grid nodes that can accept the session.
- Reliability: Prefer standard capability names and documented vendor extensions. Keep configuration close to the browser Options object and use explicit waits for dynamic UI.
- Cost: Selenium itself does not determine a remote Grid or cloud provider’s pricing. Check the selected provider’s current plan and billing rules; this dossier does not establish a general rate.
8. Or skip the browser setup
If your goal is a screenshot rather than an interactive browser test, ScreenshotNeo is a website screenshot API and MCP server for developers. A single GET request returns an image or PDF, without setting up a Selenium browser session. See the ScreenshotNeo API documentation for options and response details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed; response headers report the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
Sign up for 1,000 free screenshots a month, with no card required.
9. FAQ
Does Selenium 4 still use DesiredCapabilities?
For normal driver setup, use browser Options classes. Desired Capabilities remains a familiar term for the session configuration model and appears in legacy code and API references.
Can I request more than one browser configuration?
The W3C capabilities model supports ordered firstMatch alternatives, while alwaysMatch contains requirements. In typical Selenium application code, configure the browser Options object and let Selenium form the session request.
Does pageLoadStrategy="none" make a test wait-free?
No. It changes when navigation returns. Your test still needs to wait for the elements or state it relies on.
Where should I check whether a capability is supported?
For standard capabilities, consult Selenium’s WebDriver documentation. For browser- or provider-specific extensions, check the current documentation for that browser driver, Grid, or cloud provider.
