Selenium 3.0: What Changed and How to Upgrade

Short answer: Selenium 3.0 was intended as a straightforward dependency upgrade for projects already using WebDriver. Selenium’s public WebDriver APIs remained stable. The largest architectural change was the removal of the original Selenium Core implementation in favor of one backed by WebDriver, so legacy Selenium RC users were most likely to need migration work. Selenium Grid users should review JSON configuration and launch options.

This is a historical upgrade guide, not a current browser support matrix. Selenium 3.0 was released in 2016; Selenium’s downloads archive now lists Selenium 4 releases alongside archived Selenium 3 artifacts. For a current project, verify the exact binding, browser, and driver combination in the official documentation and archive before changing dependencies. Selenium 3.0 release announcement · Selenium 4 upgrade guide · Selenium downloads.

What changed in Selenium 3.0

Area	What changed	What to do
WebDriver APIs	The project said the public APIs were unchanged and described 3.0 as a drop-in replacement for Selenium 2.x WebDriver usage.	Update the binding dependency, then run the existing suite against the target runtime and browsers.
Selenium Core and RC	The original Selenium Core implementation was removed and replaced with a WebDriver-backed implementation. Selenium RC APIs moved to a legacy package.	Identify RC calls and test their assumptions separately. Prefer migrating them to WebDriver where practical.
Grid	The JSON configuration format and some command-line options changed.	Review the deployed JSON and startup scripts against documentation for the precise Grid version.
Firefox driver	At the time, Firefox 48 required Mozilla geckodriver, whether the suite used Selenium 2 or 3.	Treat this as historical context, not a modern compatibility rule; check current browser-driver compatibility.

The Selenium project summarized the architectural change in its official 3.0 announcement: the original Selenium Core implementation was replaced with one backed by WebDriver. Its drop-in guidance applies to WebDriver APIs; it is not a guarantee that every environment or driver combination behaves identically.

Before upgrading: identify your Selenium API

1. Search for WebDriver usage. Calls such as new ChromeDriver(), new FirefoxDriver(), or interfaces such as WebDriver indicate the supported WebDriver path.
2. Search for RC usage. Look for older Selenium RC clients, server setup, or APIs tied to the old Selenium Core model. Keep these on the migration checklist rather than assuming the dependency update is all that is needed.
3. Check whether you run Grid. Find the Grid JSON file and the exact command or service configuration used to launch hubs and nodes.
4. Record the environment. Capture language binding, Selenium version, browser versions, driver versions, Grid topology, and build command so failures can be attributed to a specific change.
5. Choose the actual target. If the goal is Selenium 3.0, use the 3.0 release guidance. If the project is moving from a later Selenium 3.x to Selenium 4, follow the separate Selenium 4 upgrade guide.

Upgrade a Java WebDriver project

For a Java project using WebDriver, change the Selenium dependency to the intended 3.0.x release, align Selenium artifacts to the same version, and run the existing tests. This example uses Maven and the historical 3.0.0 release to make the change concrete; confirm artifact availability and compatibility in your project’s dependency repository before adopting it today.

Maven

<properties>
  <selenium.version>3.0.0</selenium.version>
</properties>

<dependencies>
  <dependency>
    <groupId>org.seleniumhq.selenium</groupId>
    <artifactId>selenium-java</artifactId>
    <version>${selenium.version}</version>
  </dependency>
</dependencies>

Run the project’s normal verification command, for example mvn test, and inspect the resolved dependency tree if an older transitive Selenium artifact remains. Keep all Selenium components at a consistent version to avoid classpath conflicts.

Gradle

ext {
    seleniumVersion = '3.0.0'
}

dependencies {
    testImplementation "org.seleniumhq.selenium:selenium-java:${seleniumVersion}"
}

For older Gradle builds, the configuration may be named testCompile rather than testImplementation; use the configuration supported by the Gradle version already in the project. Do not change the build tool version as part of the Selenium dependency change unless it is independently required.

Minimal WebDriver smoke test

import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;

public class SmokeTest {
    public static void main(String[] args) {
        WebDriver driver = new ChromeDriver();
        try {
            driver.get("https://example.com");
            System.out.println(driver.getTitle());
        } finally {
            driver.quit();
        }
    }
}

This smoke test assumes the matching browser driver is installed and discoverable by the environment. Selenium 3.0 does not remove the need to manage browser-driver compatibility.

Upgrade Selenium RC users

RC is the migration risk area. Selenium’s 3.0 guidance moved RC APIs to a legacy package because WebDriver was the actively supported API. The project directed Java users who still required RC to the org.seleniumhq.selenium:selenium-leg-rc:3.0.0 artifact or later, while strongly recommending against retaining that path unless necessary.

<dependency>
  <groupId>org.seleniumhq.selenium</groupId>
  <artifactId>selenium-leg-rc</artifactId>
  <version>3.0.0</version>
</dependency>

Confirm the exact artifact version in the project’s release archive before changing a present-day build. Then inventory RC-specific calls and behaviors, make a representative test pass on the legacy dependency, and plan to replace the remaining RC interactions with WebDriver. Avoid treating successful compilation as proof of behavioral compatibility.

Upgrade Selenium Grid

Grid upgrades were described as generally straightforward, but Selenium 3.0 called out updates to JSON configuration and some command-line options. There is no single safe replacement configuration to paste here because the right settings depend on your Grid topology and exact release.

1. Find the actual JSON file and launch command used in production or CI, not only a sample checked into the repository.
2. Compare each capability, node registration setting, and command-line flag with the Selenium documentation for the target 3.0 version.
3. Start one hub and node in a non-production environment and verify session creation, browser selection, and session teardown.
4. Update service definitions, shell scripts, container arguments, and CI variables together with the JSON file.
5. Roll out gradually and retain the prior configuration so you can restore the previous Grid while investigating environment-specific failures.

Firefox and geckodriver: understand the historical timing

Firefox 48’s geckodriver requirement coincided with the Selenium 3.0 release period, but it was not caused by the Selenium version bump. Selenium’s October 2016 guidance said geckodriver was required for Firefox 48 whether a project used Selenium 2 or Selenium 3. Do not use that dated statement as a present-day browser-driver matrix. Check the official compatibility guidance for your exact browser and driver versions.

Verification checklist

• Confirm the expected Selenium binding version is actually resolved at runtime.
• Run a short browser startup and navigation smoke test in each target browser.
• Run representative user workflows, including waits, alerts, frames, downloads, and teardown if the application uses them.
• For Grid, test remote session creation, requested capabilities, node registration, and session cleanup.
• For RC-dependent suites, exercise the specific interactions that previously relied on old Selenium Core behavior.
• Review logs for driver startup errors, session negotiation problems, stale dependency versions, and timeouts.
• Record the result by browser, driver, operating system, and execution mode so a passing local run does not conceal a CI or Grid issue.

Troubleshooting common upgrade problems

Symptom	Likely cause	What to check or fix
Compilation fails after the dependency change	Code uses RC APIs or an artifact moved to the legacy package; mixed Selenium versions can also cause missing classes.	Identify the failing imports, decide whether to migrate them to WebDriver or temporarily use the documented legacy artifact, and align all Selenium dependencies.
Browser does not start or driver executable is not found	The driver is missing, not discoverable, or incompatible with the browser/runtime.	Install and configure the appropriate driver for that environment and check the browser-driver compatibility guidance. Do not infer current compatibility from Firefox 48-era instructions.
Grid rejects a node or does not create sessions	Old JSON keys or command-line options may no longer match the target Grid release; capabilities may also differ.	Compare the deployed config and launch flags with documentation for the exact release, then test hub and node registration separately.
Tests compile but RC workflows behave differently	The old Selenium Core behavior was replaced by a WebDriver-backed implementation.	Isolate the failing RC assumption, reproduce it in a small workflow, and migrate that behavior to WebDriver where possible.
Only CI fails	CI may have a different browser, driver, Java runtime, filesystem permissions, or display configuration.	Compare recorded environment versions and launch options with the passing environment; make the CI driver path and browser version explicit.
Failures appear after moving to Selenium 4	This is a later migration, not a Selenium 3.0-only issue. Protocol and deprecated API transitions span Selenium 3.x and 4.	Use the official Selenium 4 upgrade guide. The current guide notes W3C support alongside JSON Wire Protocol in Selenium 3 and W3C level 1 compliance around 3.11.

Performance, reliability, and upgrade cost

The Selenium 3.0 release guidance described WebDriver usage as a drop-in upgrade and emphasized bug fixes and stability work, but the research available for this guide contains no controlled performance benchmark or measured migration-effort study. Do not assume a speed increase or a fixed upgrade duration from the version number alone.

Keep the change reviewable: upgrade the binding, validate browser and driver versions, then assess Grid and RC separately. A dependency upgrade may be small for a WebDriver-only project, while legacy RC assumptions and Grid configuration changes can require focused investigation. Run the same representative suite before and after in comparable environments to identify reliability changes in your own system.

Or skip the browser setup

If your immediate task is capturing a page rather than migrating browser automation, ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import 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}`);

ScreenshotNeo removes supported cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers report the page verdict and billing status. Its MCP server gives AI agents tools to take screenshots, inspect page information, and capture PDFs. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.

Create a free ScreenshotNeo account for 1,000 screenshots a month with no card.

FAQ

Was Selenium 3.0 a breaking change for WebDriver code?

The project described the WebDriver API change as a drop-in replacement and said the public APIs had not changed. Individual browser, driver, and environment combinations still need verification.

Did Selenium 3.0 itself complete the W3C WebDriver transition?

No. Selenium 3 supported both W3C WebDriver and the older JSON Wire Protocol; the current Selenium 4 upgrade guide says W3C level 1 compliance arrived around Selenium 3.11.

Should a new project start on Selenium 3.0?

This guide covers a historical version transition. Check the current Selenium downloads and documentation for an active project rather than treating Selenium 3.0 setup advice as current.

Does changing Selenium versions update the browser driver automatically?

Do not assume so. Browser and driver compatibility is an environment concern; verify and configure the matching driver for the target browser.