Selenium 3 vs 4: Key Differences & Upgrade Guide

Selenium 4 is the current major release of the browser automation framework, introducing native support for the W3C WebDriver protocol, a redesigned Selenium Grid, and improved relative locators. This article explains the key differences between Selenium 3 and 4 and provides a practical upgrade guide for teams moving their test suites.

Background: Why Selenium 4 Matters

Selenium 3 was a transitional release that still relied on the JSON Wire Protocol for most browser communication. Selenium 4, released in October 2021, fully adopted the W3C WebDriver standard, which had been in development for years. This shift eliminates the need for protocol translation layers, making tests more stable and reducing flakiness. The Selenium project also overhauled the Grid, making it easier to run parallel tests across multiple machines and browsers.

Key Differences: Selenium 3 vs Selenium 4

Here are the most impactful changes you will notice when upgrading:

• W3C WebDriver compliance: Selenium 4 uses the W3C protocol natively, while Selenium 3 used the JSON Wire Protocol (with W3C as an option). This means better compatibility with modern browser drivers and more consistent behavior across browsers.
• Relative locators: Selenium 4 introduces withTagName(), above(), below(), toLeftOf(), toRightOf(), and near() to locate elements based on their position relative to other elements. This reduces the need for complex XPath or CSS selectors.
• New Window and Tab management: The newWindow() method lets you open a new tab or window and switch to it in one call, instead of the old workaround of sending keyboard shortcuts.
• Improved Selenium Grid: The Grid in Selenium 4 is rewritten to support four roles (router, distributor, node, and session map), making it more scalable and easier to configure with Docker.
• Better logging and observability: Selenium 4 includes built-in support for logging with the Java Logging framework and can export traces for debugging.
• Deprecated methods removed: Many outdated methods from Selenium 3 (e.g., Actions with moveByOffset without a context) have been removed or replaced.

Upgrade Guide: Step-by-Step

Upgrading from Selenium 3 to 4 is mostly straightforward, but you need to check your existing code for deprecated APIs. Follow these steps:

1. Update the dependency: Change the Selenium version in your build file (e.g., pom.xml for Maven, build.gradle for Gradle, or package.json for npm). Use the latest stable 4.x version.
2. Update browser drivers: Ensure you have the latest chromedriver, geckodriver, or EdgeDriver that supports W3C. Selenium 4 works with drivers that support the W3C protocol; old drivers may not work.
3. Replace deprecated APIs: Run your test suite and fix any compilation errors. Common replacements include:
• WebDriverWait with ExpectedConditions – still works, but consider using Duration instead of long for timeouts.
• Actions – the build() method is no longer needed before perform().
• Capabilities – use MutableCapabilities or DesiredCapabilities carefully; Selenium 4 prefers Options classes.
4. Update your Grid configuration (if using Grid): The old -role hub and -role node commands are replaced with a single selenium-server jar that can run in standalone, hub, or node mode with new flags.
5. Test your locators: If you used XPath or CSS selectors that relied on the old protocol, they should still work, but verify them in the new browser versions.
6. Run a smoke test: Start with a small subset of tests to catch runtime issues before running the full suite.

Common Problems and How to Fix Them

Many teams encounter similar issues when upgrading. Here are the most frequent ones:

• “SessionNotCreatedException� – This usually means the browser driver is outdated or does not support W3C. Update your driver to the latest version.
• Timeouts not working as before – In Selenium 4, WebDriverWait uses Duration instead of seconds as a long. If you pass a number, it is treated as milliseconds, not seconds.
• Actions class behavior changes – The moveToElement method now requires a visible element; otherwise, it may throw an error. Ensure the element is in the viewport.
• Grid connection failures – If you are upgrading a Grid, check that all nodes are running the same version of the Selenium server. Mixing versions can cause session errors.

How to Choose Between Selenium 3 and 4

For new projects, always start with Selenium 4. It is the only version receiving regular updates and security fixes. For existing projects, the upgrade is recommended unless you have a legacy reason to stay on Selenium 3 (e.g., an old browser driver that only supports the JSON Wire Protocol). Even then, you should plan a migration because browser vendors are dropping support for older drivers.

Comparison with Other Tools

Selenium 4 is often compared with Playwright and Cypress. While Selenium remains the most widely used and language-agnostic (Java, Python, C#, Ruby, JavaScript), Playwright offers better auto-waiting and built-in test runner, and Cypress is popular for front-end developers but only supports JavaScript. Selenium 4’s advantage is its maturity and support for all major browsers, including Safari, which Playwright and Cypress have limited support for.

Frequently Asked Questions

Is Selenium 4 backward compatible with Selenium 3?

Mostly yes, but not completely. The core APIs like WebDriver, WebElement, and By remain the same. However, some deprecated methods were removed, and the Grid configuration changed. You will need to fix compilation errors after upgrading.

Do I need to update my browser drivers when upgrading to Selenium 4?

Yes. Selenium 4 requires drivers that support the W3C protocol. Older drivers that only speak the JSON Wire Protocol will not work. Download the latest driver for your browser version.

Can I use Selenium 4 with Internet Explorer?

Selenium 4 still supports IE, but only via the IE Driver, and it is recommended to use the W3C mode. However, Microsoft has ended support for IE, so it is better to migrate to Edge or Chrome.

What is the best way to handle waits in Selenium 4?

Use WebDriverWait with Duration and ExpectedConditions. For example: new WebDriverWait(driver, Duration.ofSeconds(10)).until(ExpectedConditions.visibilityOfElementLocated(By.id("foo"))). Avoid fixed sleeps.

Does Selenium 4 support relative locators in all languages?

Yes, relative locators are available in Java, Python, C#, and JavaScript bindings. The syntax is similar: driver.findElement(withTagName("button").below(By.id("name"))).

How do I run Selenium 4 Grid with Docker?

Use the official selenium/hub and selenium/node-chrome images. For example: docker run -d -p 4444:4444 --name selenium-hub selenium/hub:4.0.0, then connect nodes with --link selenium-hub. The new Grid also supports a single standalone container for simple setups.

Related

• Used Wacom Tablet Registration: What You Can and Can’t Do
• Xiaomi 17T vs 17T Pro: Worth the Extra Cost?
• Ctrl Alt Del Remote Desktop: Fixes & How-To