Selenium 4 is a major version because it completes Selenium’s move from legacy JSON Wire Protocol behavior to the W3C WebDriver standard. For many Selenium 3 projects that already used W3C-compatible sessions, the upgrade may require few behavior changes. Projects relying on legacy capabilities, protocol conversion, or removed binding APIs can encounter session-creation failures or compilation errors.
Why Selenium 4 is a major version
During the transition from the JSON Wire Protocol to W3C WebDriver, Selenium 3 supported both protocols. That compatibility required conversion and handshake logic to translate legacy capabilities and commands, creating edge cases and maintenance burden. Selenium 4 removes legacy protocol support and uses W3C WebDriver behavior. The Selenium project announced that remaining legacy support would be removed in Java and Grid in Selenium 4.9; other language bindings had already removed their handshake code. Selenium’s upgrade guide and its legacy protocol announcement explain the transition.
The practical effect depends on your existing code and environment. W3C-compliant Selenium 3 sessions should generally continue to work, but old capability maps, assumptions about protocol conversion, and obsolete APIs may not. The upgrade guide identifies capabilities and the Actions class as areas to review.
What to audit before upgrading
Record your current setup
- Language binding and exact Selenium version.
- Browsers and browser-driver versions used in tests.
- Whether sessions run locally or remotely, and the Grid version if applicable.
- Any cloud provider and its documented capability format.
- How the project selects and provisions browser drivers.
Search application code and shared test helpers for legacy capability maps, deprecated APIs, and assumptions about session handshakes. The upgrade guide’s examples are binding-specific, so follow the section for your language rather than treating one list as exhaustive.
Recommended Free Tools
#1 Best Overall
Review session capabilities
Prefer each browser’s Options class and standard W3C capability names. The Selenium guide lists names including browserName, browserVersion, platformName, acceptInsecureCerts, pageLoadStrategy, proxy, timeouts, and unhandledPromptBehavior. Put non-standard browser, Grid, or cloud settings in the vendor’s documented prefixed options container. Avoid depending on unprefixed custom keys or deprecated DesiredCapabilities patterns.
Binding-specific code changes
The following are documented examples, not a complete changelog for every binding or provider. Consult the official upgrade guide and the release notes for your binding before considering an upgrade complete.
Java: use Duration for waits and timeouts
Wait and timeout APIs use java.time.Duration instead of the older (long, TimeUnit) form. This applies to APIs including WebDriverWait, FluentWait.withTimeout, and pollingEvery. For example, replace an older wait construction with the Duration-based form:
WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(10));Import java.time.Duration. The Java FindsBy utility interfaces were also removed; the Selenium guide describes them as intended for internal use.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Python: use By, Service, and Options
Python’s find_element_by_* methods were removed in Selenium 4.3. The executable_path and desired_capabilities keyword arguments were removed in 4.10. Use find_element(By...), a browser-specific Service, and options= instead:
from selenium import webdriver
from selenium.webdriver.common.by import By
from selenium.webdriver.chrome.service import Service
from selenium.webdriver.chrome.options import Options
options = Options()
service = Service("/path/to/chromedriver")
driver = webdriver.Chrome(service=service, options=options)
try:
driver.get("https://example.com")
heading = driver.find_element(By.TAG_NAME, "h1")
print(heading.text)
finally:
driver.quit()If Selenium Manager is suitable for your environment, you can omit the explicit Service path and let Selenium locate a driver:
from selenium import webdriver
from selenium.webdriver.chrome.options import Options
options = Options()
driver = webdriver.Chrome(options=options)C#: use AddAdditionalOption
For additional vendor options, replace deprecated AddAdditionalCapability calls with AddAdditionalOption, following the provider’s documented options structure.
Choose a driver-provisioning approach
Selenium Manager is included with Selenium beginning in 4.6. It can discover an installed browser, resolve a matching driver, download it, and cache it. The Selenium project says browser-download support was added beginning in 4.11. See the Selenium documentation and Python API documentation for these version-specific details.
Free tools Windows power users keep installed
One-click scans. No signup required.
| Approach | Useful when | Check before adopting |
|---|---|---|
| Selenium Manager | You want Selenium to locate or resolve drivers in a standard local setup. | Network access, proxy rules, browser installation, and your policy for driver/browser pinning. |
| Manually provisioned browser and driver | Your CI image or organization requires controlled, preselected versions. | That the selected browser and driver are compatible and that the executable path is supplied through the binding’s supported setup API. |
Neither approach is universally preferable: restricted networks, custom browser images, and strict pinning policies can make manual provisioning the more predictable choice.
Run a staged migration and verify real sessions
- Update the binding dependency to the Selenium 4 version selected for your project.
- Modernize capabilities using browser Options and W3C-standard names; move provider-specific values into the provider’s documented options block.
- Replace removed APIs for your binding, including the examples above where applicable.
- Confirm driver provisioning works in each local, CI, Grid, or cloud environment you use.
- Compile and run representative tests for every supported browser and session path. Include session creation, waits, Actions, and customized capabilities.
A direct in-place upgrade may suit a small project with few legacy APIs. A staged cleanup can reduce risk in a larger suite: first identify and replace old setup patterns, then upgrade and validate each execution path. The right rollout depends on the number of affected helpers and whether you can run old and new paths during the transition.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting common migration failures
Session creation fails after the dependency upgrade
Inspect the capabilities sent to the browser, Grid, or cloud provider. Replace legacy or unprefixed custom capability keys with standard W3C names and the provider’s documented vendor-prefixed options. Confirm that the target endpoint and its Grid or provider version support the requested session configuration.
The project no longer compiles
Search for removed or changed binding APIs. In Java, check wait and timeout calls that still pass a number with TimeUnit, as well as uses of FindsBy. In Python, replace removed find_element_by_* calls and old driver-construction keywords. In C#, migrate deprecated additional-capability calls.
The browser starts locally but not in CI
Compare the CI image’s browser installation, network and proxy access, and driver-provisioning policy with your local setup. If using Selenium Manager, confirm it can reach the required sources under the CI network rules. If the environment intentionally blocks downloads, provision a compatible browser and driver in the image and configure the supported Service path.
A cloud or Grid session rejects custom settings
Check the provider’s current capability documentation. Standard W3C capabilities belong at the session’s standard capability level; provider-specific settings generally belong in the provider’s prefixed options container. Do not assume a capability accepted by a local browser will be accepted unchanged by a remote endpoint.
Or skip the browser setup
If your task is to capture a website rather than automate browser interactions, ScreenshotNeo offers a screenshot API and MCP server. A GET request returns a PNG, JPEG, WebP, or PDF. For example, this cURL request saves a WebP screenshot; see the ScreenshotNeo API documentation for parameters 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.webpScreenshotNeo accepts cookie and consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, with response headers indicating 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 with no card; paid plans start at $5 for 3,000 shots. Learn more at ScreenshotNeo.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsSign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
Frequently Asked Questions
Does upgrading to Selenium 4 mean rewriting every test?
No. Selenium says code already compliant with W3C requirements should generally continue to work; the work is concentrated in legacy protocol assumptions and binding APIs that changed or were removed.
Which Selenium 4 version introduced Selenium Manager?
It is bundled beginning with Selenium 4.6. The Selenium project says browser-download support begins with 4.11.
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.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →
