To migrate a Selenium 3 suite, first confirm its language binding, runtime, and browser-driver setup; then update Selenium through the project’s package manager, fix W3C capability names and binding-specific API changes, and run the suite against the Selenium 4 version you intend to keep. Selenium 4 removes the legacy JSON Wire Protocol in favor of W3C WebDriver. Selenium’s guide says W3C-compliant code from the latest Selenium 3 is expected to work, but capabilities and Actions are the main areas that may require attention. Selenium’s migration guide
1. Inventory the suite before changing it
Make the upgrade in a branch and record the current baseline. This makes failures introduced by the migration easier to distinguish from existing test instability.
As an Amazon Associate I earn from qualifying purchases.
- Identify the Selenium language binding and how its dependency is declared: for example, Maven or Gradle for Java, pip for Python, NuGet for .NET, RubyGems for Ruby, or npm for JavaScript.
- Record the language runtime and version, especially the Java runtime.
- Record browser versions, whether tests run locally or on a remote Grid/cloud provider, and how browser drivers are installed or discovered.
- Run the existing suite and save the test results and relevant driver/browser logs.
- Search for capabilities, custom cloud options, explicit and implicit waits, driver construction, and deprecated APIs. Pay particular attention to Actions code and capability names.
Do not change the browser, runtime, test framework, and Selenium dependency all at once unless required. Keeping other variables steady makes a failed test more diagnosable.
2. Check runtime and target-release compatibility
Choose a specific Selenium 4 release before editing the dependency. The official Selenium 4.47 announcement is dated August 10, 2026 and covers JavaScript, Ruby, Python, .NET, Java, and Grid. Its changes include BiDi implementation updates, .NET command-option changes, Firefox CDP access changes in .NET, Python, and Ruby, and Selenium Manager fixes. These details can affect an upgrade even when core test code is unchanged, so read the release notes for the exact version being adopted. Selenium 4.47 release announcement
#1 Best Overall
Java runtime requirement
Selenium 4.13 was the last release with Java 8 support. The Selenium team advised upgrading to at least Java 11 for later releases. Check both the runtime used locally and the runtime configured in CI before selecting a newer Selenium version. Selenium 4.13 release announcement
Resolve the dependency using the current registry
Update the dependency with the project’s normal package manager, but do not copy version pins from old migration-guide examples: those examples illustrate where a dependency is declared and use 4.4.x-era versions. Check the package registry and the target release’s runtime requirements when choosing a version. The migration guide was modified July 29, 2025; the official release stream identified here has since reached 4.47.
Rank #2
- Update only the Selenium dependency first where practical, keeping the project’s lockfile or dependency-management process intact.
- Resolve and build the project, then inspect dependency-resolution output for conflicts or unexpected version changes.
- Commit the dependency and lockfile changes separately from code fixes when that fits the project’s workflow.
3. Replace legacy protocol capabilities
Selenium 4 uses W3C WebDriver and no longer supports the legacy JSON Wire Protocol. Standard capability keys should use W3C names. In particular, replace version with browserVersion and platform with platformName.
| Legacy or common value | Selenium 4 / W3C handling |
|---|---|
version |
Use browserVersion. |
platform |
Use platformName. |
browserName, acceptInsecureCerts, pageLoadStrategy, proxy, timeouts, unhandledPromptBehavior |
These are standard capability names; use the W3C spelling and the binding’s supported capability APIs. |
Non-standard browser or cloud keys, such as build or name |
Use the browser vendor’s required prefix or put cloud-specific values in that provider’s documented options object. Follow the provider’s current instructions for the exact prefix and structure. |
Do not send a non-standard key as if it were a standard capability. A session-creation error after the dependency update often points to an invalid capability name, a missing vendor prefix, or a cloud options object in the wrong shape.
4. Apply fixes for the language binding
Java: use Duration for timeouts and waits
Replace timeout calls that pass a numeric value and TimeUnit with the Duration-based APIs. For example:
driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(10));
driver.manage().timeouts().scriptTimeout(Duration.ofMinutes(2));
driver.manage().timeouts().pageLoadTimeout(Duration.ofSeconds(10));Import java.time.Duration. Also remove uses of Selenium’s FindsBy interfaces: they were intended for internal use and were removed. Use the supported locator APIs exposed by the Selenium binding instead.
Python: construct the driver with a Service object
The old executable_path constructor parameter is deprecated. Create a driver-specific Service and pass it as service; alternatively, make the driver available on PATH and use the binding’s normal driver discovery.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchfrom selenium import webdriver
from selenium.webdriver.chrome.service import Service as ChromeService
service = ChromeService(executable_path="/path/to/chromedriver")
driver = webdriver.Chrome(service=service)
try:
driver.get("https://example.com")
finally:
driver.quit()Replace the example driver path with the path on the machine running the test. If the driver is already discoverable through PATH, omit the explicit Service path and construct the browser using the supported defaults for your installed binding.
.NET, Ruby, and JavaScript
Update the binding through its existing package manager, then read that binding’s deprecation output and the notes for the chosen Selenium release. The official migration guide’s package commands are illustrative, not current version recommendations. Avoid applying Java- or Python-specific edits mechanically to these bindings.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.5. Run the suite and isolate failures
- Resolve dependencies and compile or import the project before launching browsers. Fix package or runtime errors first.
- Run a small representative test locally, including a test that creates a session with the project’s normal capabilities.
- Run the full suite in the same browser and CI/Grid configuration used for the baseline.
- Compare failures with the saved Selenium 3 baseline. Group them by session creation, locator/API errors, timing, Actions, browser-driver startup, or application behavior.
- Fix one category at a time, rerun the smallest affected test set, and then run the full suite again.
- After the suite passes, check the release notes for the exact target version and verify the same dependency and runtime in CI.
Selenium’s migration guidance identifies capabilities and Actions as the principal areas that may affect users. If failures cluster around pointer, keyboard, or other interaction sequences, inspect the Actions usage against the binding and target release rather than treating every failure as a browser-driver problem.
6. Troubleshoot common migration failures
| Symptom | Likely cause | What to check or change |
|---|---|---|
| Session creation fails after upgrading | A legacy capability name or an unprefixed vendor-specific key is being sent. | Replace version/platform with browserVersion/platformName; use the vendor’s required prefix and options object for non-standard values. |
| Java compilation fails on timeout calls | The code still uses numeric timeout values with TimeUnit. |
Use the applicable Duration-based timeout method and import java.time.Duration. |
Java compilation fails on FindsBy |
The suite depends on an interface removed from Selenium 4. | Replace it with supported locator APIs in the Java binding. |
Python rejects executable_path |
Driver construction still uses the deprecated constructor parameter. | Pass a driver Service object as service, or make the driver available on PATH. |
| Java dependency or runtime fails with a newer Selenium release | The selected release may require a newer Java runtime; Java 8 support ended after Selenium 4.13. | Confirm the Java version used by local development and CI; upgrade to at least Java 11 for releases after 4.13, or select a compatible target while planning the runtime upgrade. |
| Only remote cloud sessions fail | Cloud-specific capabilities may be encoded using the old provider format. | Check the provider’s current Selenium 4 documentation for its vendor prefix and options object; do not assume generic keys such as build or name are standard. |
| Tests fail around browser interactions | An Actions sequence or version-specific behavior may have changed or be exposed by the upgrade. | Reduce the failure to a small interaction test, inspect the binding’s current API and target release notes, and verify browser and driver versions are the intended ones. |
Or skip the browser setup
For capturing a page screenshot as part of a workflow, ScreenshotNeo offers a single GET request without setting up a browser locally. Its API removes cookie banners, newsletter popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. An MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsExample cURL request, using the documented API endpoint and parameters:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for setup and options. Sign up for 1,000 free screenshots a month with no card.
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.
