Selenium 3: What to Expect and How to Prepare

If you are still using Selenium 3, treat it as a legacy version you are maintaining while you plan a move to Selenium 4. Start by inventorying your language binding, browser and driver versions, capabilities, waits, and execution environment. Then update dependencies in a branch, fix the specific compatibility issues your suite exposes, and run representative tests against the browsers and infrastructure you use.

Selenium’s upgrade guide says W3C-compliant code in the latest Selenium 3 should work in Selenium 4. That is not a promise that every old suite upgrades unchanged: Selenium 4 removes JSON Wire Protocol support, and the guide documents API and browser-specific exceptions. [Selenium’s Selenium 4 upgrade guide]

1. What Selenium 3 users should expect

Selenium is a set of browser automation tools. WebDriver drives browsers through their vendor automation APIs; Grid distributes test execution across machines and platforms; IDE records and replays browser interactions. Identify which pieces your suite uses before changing dependencies. A local WebDriver test does not need Grid, while remote sessions need a compatible client, Grid, browser, and driver setup. [Selenium overview]

Area	What to expect	Preparation
Protocol	Selenium 3 supported W3C WebDriver and the older JSON Wire Protocol. Selenium 4 uses W3C WebDriver and removes legacy protocol support.	Find protocol assumptions, old clients, and legacy capabilities.
Capabilities	Some old Desired Capabilities and unprefixed vendor-specific settings need attention.	Prefer browser Options classes and standard W3C capability names.
Timeouts and APIs	Some signatures changed, notably Java timeout APIs that now use Duration.	Search for deprecated calls and compile after updating.
Browsers and drivers	Compatibility depends on the binding, browser, driver, and environment together.	Check the browser vendor’s documentation and version pairing.
Runtime and packages	Supported runtime minimums and package versions vary by binding and release.	Check current release documentation before selecting versions.

The Selenium project says W3C support was implemented during Selenium 3 development and that code compliant with the W3C specification in the latest Selenium 3 should work in Selenium 4. Its 2022 protocol announcement recommends Options classes over deprecated Desired Capabilities patterns. Standard capability names include browserName, browserVersion, platformName, acceptInsecureCerts, pageLoadStrategy, proxy, timeouts, and unhandledPromptBehavior. For vendor-specific or cloud capabilities, follow the provider’s required prefix or Options container. [Upgrade guide] [Selenium: Removing Legacy Protocol Support]

2. Audit the existing suite

1. Record the baseline. Note Selenium client and language versions, build tool, runtime, browser versions, driver versions, operating systems, and whether execution is local or on Grid. Save a representative test run and its logs.
2. Find protocol and capability assumptions. Search for Desired Capabilities construction, setCapability, JSON Wire names, unprefixed vendor keys, and custom remote session setup. Replace deprecated patterns with the browser’s Options class where the binding supports it.
3. Review synchronization. Find implicit waits, explicit waits, page-load and script timeouts, fixed sleeps, and constructors for WebDriverWait. Confirm the new signatures and avoid masking flaky readiness with longer arbitrary sleeps.
4. Review browser-specific APIs. Inspect Actions, Firefox legacy automation, vendor extensions, and any code that assumes old driver behavior. Selenium’s guide flags Actions and capabilities as important migration areas and advises using GeckoDriver instead of the old Firefox legacy implementation.
5. Check test infrastructure. Identify Grid versions, remote endpoints, container images, proxy settings, secrets, browser policies, and network access needed to obtain drivers. Keep local and remote configurations distinct.
6. Set a controlled upgrade target. Choose a supported Selenium 4 release and compatible language runtime based on the official downloads and package sources. Do not copy old example version numbers blindly; release requirements change.

Selenium’s current downloads page is the source of truth for releases and bindings: selenium.dev/downloads. Selenium Manager is used by bindings to help manage browsers and drivers, but restricted networks, pinned browsers, and enterprise policies may still require explicit configuration. [Selenium Manager documentation]

3. Update dependencies by language

Use the package manager already used by the project, update to a current compatible Selenium 4 release, commit the lockfile or dependency resolution, and compile before running the full suite. The examples below show the package routes; consult the linked current upgrade guide and registries for version and runtime requirements.

Python

python -m pip install --upgrade selenium
python -m pip show selenium

The Selenium upgrade guide version retrieved for this research lists Python 3.7 or higher as its minimum for Selenium 4; confirm the current release’s requirement before upgrading an older runtime. Keep dependencies pinned in the project’s requirements or lock file for repeatable CI installs.

Java

For Maven, update the Selenium dependency in pom.xml to the chosen Selenium 4 version, then compile:

<dependency>
  <groupId>org.seleniumhq.selenium</groupId>
  <artifactId>selenium-java</artifactId>
  <version>4.x.y</version>
</dependency>

mvn clean compile

For Gradle, update the dependency declaration to the same selected release, for example testImplementation("org.seleniumhq.selenium:selenium-java:4.x.y"), then run ./gradlew test. Replace 4.x.y with an actual version from the official release listing. The upgrade guide’s Java examples retain Java 8 as a minimum, but validate the current release requirements for your project.

C#

Update the Selenium.WebDriver NuGet package through the project file or NuGet tooling, selecting a current compatible version. Then restore and build:

dotnet restore
dotnet build

JavaScript

npm install --save-dev selenium-webdriver
npm ls selenium-webdriver

Check the supported Node.js version and package release notes for the version you resolve. Keep the package lockfile under version control so CI uses the same dependency graph.

Ruby

gem install selenium-webdriver

For an application, add selenium-webdriver to the Gemfile and run bundle install so the dependency is recorded and reproducible.

4. Fix common migration code changes

Python: use Options and explicit waits

This small Selenium 4 example launches Chrome, waits for a real page condition, and always quits the session. Selenium Manager may locate or manage the driver in supported environments; if your environment pins a driver, configure that explicitly according to Selenium and browser-vendor guidance.

from selenium import webdriver
from selenium.webdriver.chrome.options import Options
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC
from selenium.webdriver.common.by import By

options = Options()
options.add_argument("--headless=new")  # Remove this line to see the browser.

driver = webdriver.Chrome(options=options)
try:
    driver.set_page_load_timeout(30)
    driver.get("https://example.com")
    heading = WebDriverWait(driver, 10).until(
        EC.visibility_of_element_located((By.TAG_NAME, "h1"))
    )
    print(heading.text)
finally:
    driver.quit()

Avoid adding an implicit wait globally just to make a failing test pass. Mixing implicit and explicit waits can make observed wait times difficult to reason about. Prefer explicit waits for the condition the test needs, and set page-load and script timeouts only when the application requires them.

Java: move timeout arguments to Duration

Calls that previously took a numeric time and TimeUnit use Duration in Selenium 4. The migration guide shows these forms:

import java.time.Duration;
import org.openqa.selenium.WebDriver;
import org.openqa.selenium.chrome.ChromeDriver;
import org.openqa.selenium.support.ui.WebDriverWait;

WebDriver driver = new ChromeDriver();
try {
    driver.manage().timeouts().implicitlyWait(Duration.ofSeconds(10));
    driver.manage().timeouts().pageLoadTimeout(Duration.ofSeconds(30));
    WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(3));
    // Use wait.until(...) for the condition required by the test.
} finally {
    driver.quit();
}

Also inspect Options merging. The result of options.merge(capabilities) is an options object; assign and use the returned value as shown by the official guide rather than assuming the original object was changed.

5. Validate in stages

1. Compile or import. Resolve removed methods and signature changes before debugging browser behavior.
2. Run a smoke test. Launch one browser, navigate to a stable page, assert one element, and close the session.
3. Run representative tests locally. Include tests using waits, Actions, uploads/downloads, prompts, frames, windows, and custom capabilities.
4. Run against each browser and driver pair. Check the browser vendor’s compatibility guidance and record exact versions with failures.
5. Validate Grid separately. Confirm the remote endpoint, node/browser availability, capabilities, timeouts, and session cleanup. A local pass does not validate remote infrastructure.
6. Compare behavior and flakiness. Review failures, screenshots, logs, and duration against the Selenium 3 baseline. Fix synchronization and environment differences instead of automatically increasing timeouts.
7. Roll out gradually. Upgrade a small CI shard or non-blocking job first, then expand after the key browser matrix is stable.

6. Browser, driver, and Grid considerations

WebDriver depends on browser-vendor automation APIs. Treat the Selenium binding, browser, driver, and host environment as separate compatibility layers when diagnosing startup or command failures. Selenium’s downloads page points to vendor driver resources, including Chromium’s ChromeDriver and Microsoft’s Edge WebDriver. Selenium Manager can automate much of browser and driver provisioning in supported setups, but it cannot remove constraints imposed by offline builds, managed browser policies, or pinned enterprise images.

Edge has a specific migration requirement: Microsoft says Selenium 3 is not supported for automating current Chromium-based Edge. Projects using the old Selenium Tools for Microsoft Edge should remove that package, move to Selenium 4’s built-in EdgeDriver classes, and remove obsolete EdgeOptions.UseChromium usage. [Microsoft Edge WebDriver guidance]

Grid is useful when tests need multiple machines, browsers, or operating systems. It is not needed for a local browser session. With Grid, the test process is the client and a remote end executes the session; verify both ends and their network path. [Selenium Grid documentation]

7. Troubleshooting

Symptom	Likely cause	What to do
Compilation errors around timeout methods or WebDriverWait	Old numeric-plus-TimeUnit Java signatures.	Use Duration-based signatures and update imports.
Session creation fails with an unsupported command or capability error	Legacy JSON Wire Protocol assumptions, removed capability APIs, or invalid vendor capability names.	Use W3C capability names, browser Options classes, and the provider’s documented namespacing.
Driver executable cannot be found	Driver is absent, not on PATH, incompatible, or inaccessible in the runtime environment.	Check browser and driver versions; use Selenium Manager where suitable or configure a compatible driver explicitly.
Browser starts then immediately exits	Driver/browser mismatch, unsupported flags, permissions, missing libraries, or a container configuration issue.	Run a minimal launch, inspect driver logs, verify versions and OS dependencies, then reintroduce options one at a time.
Edge session fails with missing method involving DesiredCapabilities	Legacy Selenium Tools for Microsoft Edge is mixed with the newer Selenium API.	Remove the legacy package and migrate to Selenium 4’s EdgeDriver as Microsoft documents.
Element lookup is flaky after navigation	Test assumes the page is ready immediately, or relies on fixed sleeps.	Wait for the specific element or state with an explicit wait; check whether navigation or an overlay is still active.
Local tests pass but remote Grid tests fail	Remote browser versions, node capabilities, networking, certificates, or timeouts differ.	Log requested and returned capabilities, inspect Grid/node logs, and reproduce on the same browser image.
Firefox behavior differs from Selenium 3	Old Firefox legacy automation or driver assumptions.	Use GeckoDriver and current Firefox automation support; remove legacy implementation dependencies.
Driver downloads fail in CI	Network restrictions, proxy configuration, or restricted access to vendor endpoints.	Configure approved proxy/network access or provision browser and driver in the build image; do not rely on first-run downloads in an offline job.

8. Performance, reliability, and cost

Selenium itself does not make a test suite fast or reliable by changing major versions. A migration can expose slow startup, repeated driver downloads, unnecessary browser sessions, fixed sleeps, or overloaded Grid nodes. Measure the same representative tests before and after the change, separate browser startup from test execution, reuse a session only where test isolation remains sound, and close every session in cleanup paths.

For reliability, pin dependency resolution and browser images in CI, record versions in failure artifacts, use explicit condition-based waits, and avoid hiding failures with retries alone. For remote runs, monitor node capacity and network stability. Costs usually come from engineering and CI/browser infrastructure time rather than a Selenium license; Selenium is an open-source project, but hosted browser grids or cloud execution may have their own pricing. The cited Selenium documentation does not specify vendor service prices.

9. When a screenshot is enough

If a task needs a page image for visual review or documentation rather than interactive browser testing, a screenshot API can avoid maintaining a browser automation setup for that task. ScreenshotNeo is a website screenshot API and MCP server from Yorker Media. It is an alternative to try first when the job is capturing pages: cookie and consent banners, newsletter popups, and chat widgets are removed before capture; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; and its MCP server lets AI agents take screenshots. Selenium remains the right tool when the test needs to click, type, assert, or control a browser session.

10. Or skip the browser setup

For a page capture, ScreenshotNeo returns an image or PDF from one GET request. See the ScreenshotNeo API documentation for parameters and response details.

cURL

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

Python

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://example.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const fs = await import('node:fs/promises');
await fs.writeFile('shot.webp', Buffer.from(await res.arrayBuffer()));

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed, and response headers report the page verdict and billing status. An MCP server lets AI agents take screenshots. 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.

11. FAQ

Should a new project start on Selenium 3?

No. The migration guide is for teams maintaining Selenium 3; use the current Selenium 4 release and supported runtime for a new project.

Does upgrading require Selenium Grid?

No. Grid is for distributed or remote execution. A local WebDriver test can run without it.

Is Selenium 3 officially end-of-life on a specific date?

The cited official material does not establish a Selenium 3 support cutoff date. Avoid assuming one; plan based on current browser and vendor compatibility requirements.

Can a screenshot API replace Selenium tests?

No. A screenshot service captures a page; it does not replace interactive assertions and browser control in a WebDriver test.

Primary references

• Selenium: Upgrade to Selenium 4
• Selenium downloads
• Selenium Manager
• Selenium overview and Grid documentation
• Selenium: Removing Legacy Protocol Support
• Microsoft Edge WebDriver guidance