Selenium 3 vs. Selenium 4: Key Differences
Selenium 4 uses the W3C WebDriver protocol and updates capability handling. Learn what changed, how to migrate, and when Selenium Manager helps.
Selenium 4 uses the W3C WebDriver protocol exclusively. Selenium 3 supported both W3C WebDriver and the older JSON Wire Protocol during its development, though later Selenium 3 releases became W3C-compliant. The practical upgrade work is usually in capabilities, Actions, deprecated or internal APIs, and your language binding and browser setup—not in rewriting every test. See the Selenium project’s migration guide.
At a glance
| Area | Selenium 3 | Selenium 4 |
|---|---|---|
| WebDriver protocol | Supported JSON Wire Protocol and W3C WebDriver; later 3.x code became W3C-compliant. | Uses W3C WebDriver and removes legacy protocol support. |
| Capabilities | Older Desired Capabilities classes and names were common. | Use browser options classes, standard names such as browserVersion and platformName, and vendor prefixes for custom capabilities. |
| Locators | Traditional locator strategies. | Adds Relative Locators, which locate elements by spatial relationship to a known element. |
| Driver setup | Driver binaries were commonly managed manually. | Selenium Manager was added in later 4.x releases; it can manage drivers and, in later versions, browsers. |
| Upgrade risk | May rely on legacy protocol or older APIs. | W3C-compliant code should carry forward, but review capabilities, Actions, deprecated or internal APIs, and runtime compatibility. |
What changed between Selenium 3 and Selenium 4?
1. Selenium 4 standardizes on W3C WebDriver
The central change is protocol support. Selenium 3 had a transition period in which it supported the legacy JSON Wire Protocol as well as W3C WebDriver. The Selenium project says code in later Selenium 3 releases became compliant with the W3C Level 1 specification around version 3.11. Selenium 4 removes legacy protocol support.
This does not mean every Selenium 3 test must be rewritten. If your client, capabilities, and remote browser setup already follow W3C conventions, the protocol change may require little or no test-code change. Noncompliant capabilities or dependencies on old behavior are more likely to cause migration issues.
2. Capabilities use modern names and browser options
Prefer a browser-specific options class when configuring a session. Standard W3C capability names include browserVersion and platformName, replacing older names such as version and platform. Custom capabilities need a vendor prefix so they do not collide with standard capability names. For browser-specific examples and current guidance, consult the Selenium Browser Options documentation.
When connecting to a Grid or cloud provider, use that provider’s documented namespaced capabilities alongside the browser options object. Do not send an unprefixed custom capability and assume it will be accepted by every remote endpoint.
3. Relative Locators add spatial relationships
Selenium 4 adds Relative Locators for cases where a stable label, heading, or other element is easy to find but the target has no useful unique locator. You can express that a target is above, below, to the left or right of, or near a known element. They complement CSS and XPath; they do not make a fragile page structure stable. See the official locator strategies documentation.
4. Selenium Manager arrived after Selenium 4.0
Do not assume Selenium Manager was part of the original Selenium 4.0 release. It shipped with releases starting at 4.6 for driver management. Automated browser management is documented from 4.11. Manager can act as a fallback when the binding does not find a supplied driver, so explicitly managed drivers remain an option. Check the Selenium Manager documentation for its current behavior and requirements.
5. Binding and runtime requirements depend on language
Selenium is available through language-specific bindings, and runtime minimums can change. Before upgrading, check the current requirements for your binding, your browser versions, Selenium Grid, and any hosted browser service. Selenium 4.0.0 was announced on October 13, 2021; do not treat an old tutorial’s pinned version as the current release. Use the official Selenium documentation and release information for the version you intend to install.
Should you upgrade?
For an actively maintained project, plan to upgrade to a supported Selenium 4 binding. Selenium 3 code that follows W3C conventions is a better starting point, but compatibility still depends on the APIs and infrastructure your suite uses.
- Upgrade with low expected code churn: your tests use standard WebDriver calls, W3C-compatible capabilities, supported binding APIs, and a compatible browser/Grid setup.
- Budget time for migration: you use old Desired Capabilities patterns, legacy capability names, Actions sequences with unusual behavior, deprecated or internal APIs, or a remote service with custom configuration.
- Investigate before changing production CI: your language runtime, browser driver, Grid, or cloud provider has version constraints that are not yet confirmed.
The Selenium migration guide specifically highlights Capabilities and Actions as areas to review. The guide cannot establish whether a particular application suite will pass; run your own tests against the browsers and infrastructure you use.
How to upgrade a Selenium 3 project
- Record the baseline. Note the binding version, language runtime, browser versions, driver versions, Grid or cloud endpoint, and existing test results. Keep a reproducible baseline to compare failures.
- Upgrade the binding. Change the dependency with your normal package manager or build tool. Choose a version compatible with your runtime and infrastructure by checking the binding’s current official requirements rather than copying a version number from an old guide.
- Modernize session configuration. Replace legacy Desired Capabilities usage with the relevant browser options class. Rename standard capabilities to W3C names such as
browserVersionandplatformName; namespace provider-specific custom capabilities as that provider requires. - Review Actions and API usage. Inspect Actions code and search for deprecated or internal Selenium APIs. Replace unsupported patterns with documented public APIs.
- Verify driver and browser provisioning. Decide whether your environment supplies drivers, uses Selenium Manager, or provisions browsers another way. Confirm that the behavior is appropriate for local development and CI.
- Run tests in layers. Start with a small smoke suite, then the full suite on each supported browser and remote environment. Compare failures with the baseline and separate application regressions from session-start or protocol configuration failures.
- Update team setup notes. Document the supported runtime, binding, browser and driver strategy, Grid configuration, and any vendor-prefixed capabilities so local and CI sessions behave consistently.
Capability migration checklist
| Check | What to do |
|---|---|
| Browser configuration | Use the browser’s options class for arguments, preferences, and capabilities. |
| Standard names | Use browserVersion and platformName where applicable instead of legacy version and platform. |
| Custom names | Prefix nonstandard capability names with the vendor or service namespace required by the endpoint. |
| Remote session | Check the Grid or cloud provider’s current capability documentation and avoid sending conflicting values in multiple places. |
| Legacy helpers | Find code that constructs Desired Capabilities objects or calls deprecated/internal APIs; replace it with documented options and public APIs. |
Driver management: manual setup or Selenium Manager?
Manual driver management gives teams explicit control over binary versions and is often useful in pinned CI images. Selenium Manager can reduce setup work when a binding cannot find a suitable driver. It is a later Selenium 4 capability: driver management started with releases from 4.6, and automated browser management is documented from 4.11. Its availability does not remove the need to understand which browser and driver your test environment actually runs.
For a reliable CI setup, pin or otherwise control browser versions when reproducibility matters, ensure the runner can access any required downloads, and capture the browser, driver, and Selenium versions in logs. If your environment is offline or restricts downloads, provision the needed binaries yourself.
Common migration errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Session creation fails with an invalid or unrecognized capability | Legacy capability names, an unprefixed custom capability, or a capability unsupported by the remote endpoint. | Use W3C standard names, a browser options class, and the provider’s required vendor prefix. Remove unsupported values and retry. |
| Remote browser starts with unexpected settings | Options and custom capabilities conflict, or the remote service interprets a legacy field differently. | Keep each setting in one documented place and compare the outgoing configuration with the endpoint’s current documentation. |
| Driver cannot be found or downloaded | No driver is available to the binding, Selenium Manager cannot access required resources, or a manually pinned driver does not match the browser. | Check browser/driver compatibility and network policy. Either provision a compatible driver explicitly or use a supported Selenium Manager setup. |
| Compilation or import errors after dependency upgrade | Code depends on APIs that changed, were deprecated, or were internal, or the language runtime is incompatible with the selected binding. | Check the binding’s migration notes and runtime requirements; replace internal calls with supported public APIs. |
| Actions behave differently or fail | Legacy or nonstandard Actions assumptions surfaced during the protocol and API migration. | Review the Actions code against the Selenium upgrade guide, simplify the interaction sequence, and verify it in the actual browser. |
| Tests pass locally but fail in CI | Different browser, driver, runtime, download access, Grid configuration, or capability values. | Log versions and session configuration in both environments, then align provisioning and endpoint settings. |
| A Relative Locator finds the wrong element | The page has multiple candidates in the specified spatial relationship or responsive layout changes the geometry. | Anchor to a more specific known element, add a distinguishing condition, or use a stable CSS/XPath locator when spatial position is not a meaningful invariant. |
Performance, reliability, and cost considerations
Selenium 4’s protocol standardization and added APIs do not guarantee that an application’s suite will run faster. End-to-end time is usually shaped by page loading, waits, test data, browser startup, and remote network latency. Measure your own suite before attributing a timing change to the Selenium upgrade.
For reliability, keep the binding, runtime, browser, and driver strategy explicit; use stable locators; avoid relying on undocumented APIs; and test against the same kind of Grid or hosted browser service used in CI. Selenium itself is an open-source automation framework, but operating browsers and Grid infrastructure can carry compute, hosting, and maintenance costs. Cloud browser providers may have their own usage charges; check their terms directly.
ScreenshotNeo: an alternative for screenshot capture
Selenium is appropriate when you need to automate browser interactions and validate application behavior. If the task is to capture a website image or PDF, ScreenshotNeo is a purpose-built website screenshot API and MCP server from Yorker Media. It takes one GET request with a URL and returns PNG, JPEG, WebP, or PDF. The one-line reason to try it first for screenshot capture: cookie banners, popups, and chat widgets are removed before the shot, and only clean shots are billed.
Or skip the browser setup
For a screenshot, call the API directly. See the ScreenshotNeo API documentation for request options.
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', new Uint8Array(await res.arrayBuffer()));ScreenshotNeo removes cookie banners, popups, and chat widgets before capture; 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 shots. Sign up for 1,000 free screenshots a month, with no card required.
Frequently asked questions
Does Selenium 4 require rewriting Selenium 3 tests?
Usually not wholesale. W3C-compliant tests using supported APIs can carry forward, but configuration, Actions, deprecated or internal calls, and environment compatibility need review.
Was Selenium Manager included in Selenium 4.0?
No. Driver management arrived with Selenium releases starting at 4.6; automated browser management is documented from 4.11.
Are Relative Locators a replacement for CSS selectors or XPath?
No. They add a way to find elements by position relative to a known element. Use them when spatial relationships are meaningful and stable.
Where should I check the current Selenium version and requirements?
Use the official Selenium project documentation and release information, plus the requirements for your specific language binding and remote browser provider. These details can change over time.
