Selenium: W3C WebDriver Browser Automation Toolkit
GitHub Repo
Apache-2.0
November 19, 2026 at 01:55 PM
0 views

Selenium: W3C WebDriver Browser Automation Toolkit

@SeleniumHQProject Author

What Selenium is

Selenium is the long-running open-source project for automating web browsers. The repository README describes it as "an umbrella project encapsulating a variety of tools and libraries enabling web browser automation" and says it "specifically provides an infrastructure for the W3C WebDriver specification", a language-neutral interface that every major browser implements. The README's own tagline is shorter: "Automates browsers. That's it!"

In practice "Selenium" means several things. WebDriver is the client library you call from Java, Python, JavaScript, Ruby or C# (Kotlin uses the Java bindings). Selenium Grid is a Java server that routes WebDriver sessions to remote machines. Selenium IDE is a browser extension that records and replays actions. The overview page in the documentation adds Selenium Manager, a Rust command-line tool that finds or downloads the right driver and browser, and the bindings call it for you.

The audience is QA engineers writing end-to-end suites, developers adding a CI smoke test, and anyone scripting a real browser. The docs are explicit that WebDriver "does not know a thing about testing": it drives a browser, and assertions, fixtures and reports come from a test runner such as JUnit, NUnit, pytest or RSpec. That layering is different from unit-level frameworks like GoogleTest, which never leave the process under test.

The code lives in the SeleniumHQ/selenium monorepo on the trunk branch. Java is the primary language, and the Python, JavaScript, Ruby and .NET bindings, the Grid server and Selenium Manager all sit side by side, built with Bazel. The GitHub repository dates from January 2013, but PyPI's history for the selenium package starts with 0.9.2 in April 2008; 4.0.0 arrived in October 2021. The licence is Apache-2.0, with the copyright notice naming the Software Freedom Conservancy.

How it works: bindings, drivers, Selenium Manager and Grid

Bindings talk to a browser-specific driver

A Selenium script never touches the browser directly. The bindings send W3C WebDriver commands over HTTP to a driver executable (chromedriver for Chrome, geckodriver for Firefox, msedgedriver for Edge, safaridriver for Safari), and that driver controls the browser. The documentation's "Details" page explains that this split is deliberate: browser vendors take responsibility for their own drivers, and Selenium supplies the uniform client API on top. The history page recounts how the project moved from drivers it built itself to separate vendor executables, and why Firefox 48's ban on unsigned extensions made geckodriver mandatory.

Selenium Manager resolves drivers and browsers

Since Selenium 4.6, every release ships Selenium Manager binaries, and the bindings call them when no driver is configured. The Selenium Manager docs list four steps: detect the installed browser version (for example by running google-chrome --version), resolve the matching driver from vendor metadata such as the Chrome for Testing JSON endpoints, download it, and cache it in ~/.cache/selenium. Since 4.11.0 it can also download Chrome for Testing, Firefox (from 4.12.0) and Edge (from 4.14.0) when none is installed, or a specific browserVersion such as stable, beta or a major number. Resolved versions are cached for a one-hour TTL, and cache entries unused for 30 days are pruned automatically.

Selenium Manager is a fallback: a driver path set in code, a driver on PATH or an environment variable such as SE_CHROMEDRIVER take priority. The docs also say plainly that "Data collection is on by default": Selenium Manager reports the Selenium version, language binding, OS, architecture, browser version and a rough IP-derived location to Plausible, and SE_AVOID_STATS=true turns it off. Offline mode, mirror URLs and a proxy setting cover restricted networks.

Grid routes sessions to remote browsers

Grid is a Java server. The Grid docs describe six components (Router, Distributor, Session Map, New Session Queue, Event Bus and Node) that can run as one standalone process, as hub and nodes, or fully distributed. A node discovers drivers on PATH, or uses Selenium Manager when started with --selenium-manager true. Clients point RemoteWebDriver at http://localhost:4444 or wherever the router lives. The Grid quick start lists Java 11 or higher; building Selenium itself, per the README, needs JDK 17.

WebDriver Classic, WebDriver BiDi and CDP

Classic WebDriver is strictly request and response, which is predictable but cannot stream events such as console messages or network requests. The CDP page in the docs says Chrome DevTools Protocol support "is temporary until WebDriver BiDi has been implemented", and that Selenium supports "the 3 most recent versions of Chrome at any given time". Each binding ships generated CDP classes for those versions; the 4.53.0 changelogs list v155, v156 and v157.

WebDriver BiDi is the W3C replacement, which the BiDi page says was "created by the Selenium project together with the browser vendors". It adds a WebSocket to the session so scripts can subscribe to events across browsers. In Python you enable it with options.enable_bidi = True, then register handlers on driver.script for console messages and JavaScript errors. The docs mark several high-level BiDi helpers as not yet implemented in some bindings (the logging page shows JavaScript and C# as pending), so coverage is uneven. Recent changelogs are dominated by BiDi work, such as generating each binding's protocol layer from a shared schema.

Key features

  • Five official bindings. Java, Python, JavaScript (Node.js), Ruby and C#/.NET, all released together with the same version number.
  • Standards-based browser support. Chrome, Edge, Firefox and Safari through vendor drivers; the Python package README also lists WebKitGTK and WPEWebKit.
  • Automatic driver and browser management. Selenium Manager detects the browser, fetches a matching driver and can download Chrome for Testing, Firefox or Edge, with offline mode, mirrors, a proxy setting and a TOML config file.
  • Explicit and implicit waits. WebDriverWait polls any condition; Java and Python ship ready-made expected conditions, .NET and Ruby take a lambda or block.
  • Relative locators. Locate elements by position relative to others; 4.53.0 for Python lets them start from a WebElement or shadow root.
  • BiDi event handlers. Console message and JavaScript error handlers, with network interception and other domains in progress.
  • Accessibility snapshot. New in 4.53.0: the Python and JavaScript changelogs add an accessibility-tree snapshot built on a shared JavaScript atom, available in both Classic and BiDi sessions.
  • Selenium Grid. Standalone, hub-and-node or distributed deployments for parallel runs across machines, operating systems and browser versions.

Getting started

Install the binding for your language. Python, from the package README:

pip install -U selenium

Node.js, from the selenium-webdriver README (which requires Node.js 22.23.4, 24.22.1 or 26.12.1 or newer):

npm install selenium-webdriver

Ruby and .NET, from the getting-started guide:

gem install selenium-webdriver
dotnet add package Selenium.WebDriver

The smallest Python script, from the Python package README, opens Chrome, loads a page and quits. Selenium Manager finds or downloads chromedriver behind the scenes:

from selenium import webdriver
driver = webdriver.Chrome()
driver.get("https://selenium.dev")
driver.quit()

Dynamic pages need a wait. The documentation's Python example waits up to two seconds for a hidden field to become visible:

wait = WebDriverWait(driver, timeout=2)
wait.until(lambda _ : revealed.is_displayed())

To see what Selenium Manager does on a given machine, run the binary with debug output, as in the Selenium Manager docs:

$ ./selenium-manager --browser chrome --debug

A local Grid takes one command once the server jar is downloaded (the docs also show ./selenium-manager --grid to fetch it):

java -jar selenium-server-<version>.jar standalone

Node.js scripts can then be redirected to it without code changes, per the JavaScript README:

SELENIUM_REMOTE_URL="http://localhost:4444" node script.js

Contributors build the repository with Bazel; the README gives a short alias for the Grid:

bazel build grid

Hands-on: Selenium 4.53.0 in a Linux VM

Everything in this section was run on 19 November 2026 in a cloud VM: Ubuntu 24.04.5 LTS, x86_64, 2 vCPUs, about 7 GB RAM, Python 3.13.18, Node.js 22.23.5 and OpenJDK 21.0.13. The browser was a preinstalled Chrome for Testing 153.0.8010.12, plus Playwright 1.63.0's separate headless shell (Chrome for Testing 157.0.8103.78). The VM blocks googlechromelabs.github.io and storage.googleapis.com, which is exactly where Selenium Manager looks for chromedriver. The target was a small page served by python3 -m http.server on 127.0.0.1 with a button that adds three list items and a #done element after a 1,500 ms timer, a button that re-renders the list, and two console messages. All timings are single-machine wall-clock numbers on a 2 vCPU VM and only indicative.

Install

StepObserved
pip install selenium in a fresh venv4.53.0 in 5.0 s, plus 14 dependencies including trio 0.35.0, trio-websocket 0.12.2, urllib3 2.8.0, websocket-client 1.9.2 and certifi 2026.10.23
Wheel and footprintWheel 12,240,652 bytes; installed package 28 MB, of which about 22 MB is four Selenium Manager binaries (Linux x86_64 5.5 MB, Linux arm64 4.4 MB, macOS 8.2 MB, Windows 3.8 MB)
selenium-manager --versionselenium-manager 0.4.53, matching the docs' rule that Manager uses major version 0 while "still in beta"
npm i selenium-webdriver4.53.0 in 1.7 s, 26 MB of node_modules; the same four Selenium Manager binaries under bin/

Driver resolution with and without an explicit path

The VM had chromedriver 147.0.7727.24 on PATH (from an npm chromedriver package) next to Chrome 153, a realistic stale-driver setup. A matching chromedriver 153.0.8010.36 came from the third-party PyPI package chromedriver-py, which is not part of Selenium. All runs used --headless=new and --no-sandbox (the VM runs as root).

SetupResultTime
webdriver.Chrome(), chromedriver 147 on PATHSelenium Manager logs a failed Chrome for Testing lookup ("tunnel error: unsuccessful"), warns that the 147 driver "might not be compatible" with Chrome 153, then hands it over anyway. Session fails: SessionNotCreatedException, "This version of ChromeDriver only supports Chrome version 147"1.97 s to error
Service() pointing at chromedriver 147Same SessionNotCreatedException, without the Selenium Manager step1.03 s
No driver on PATH, network blockedManager tries https://chromedriver.storage.googleapis.com//chromedriver_linux64.zip (empty version, double slash), then NoSuchDriverException: "Unable to obtain driver for chrome"0.46 s
No driver, SE_OFFLINE=true"Unable to discover proper chromedriver version in offline mode", then NoSuchDriverException0.16 s
chromedriver 147 with ChromeDriver's own --disable-build-check service argumentSession started against Chrome 153; page load and text read worked. A workaround, not a fix0.59 s
SE_CHROMEDRIVER set to the 153 driverSession started, no Manager network call0.50 s
Service() pointing at chromedriver 153Session started; five runs 0.52, 0.36, 0.38, 0.42, 0.38 s; quit() median 0.074 smedian 0.377 s
webdriver.Chrome(), 153 driver first on PATHWorks, but every start repeats the failed lookup and its warning, because nothing is cached when discovery failsmedian 0.713 s
Same, with SE_OFFLINE=trueWorks without the lookupmedian 0.521 s

For CI images and air-gapped runners: pin the driver (Service path or SE_CHROMEDRIVER) or set SE_OFFLINE=true. Otherwise each session pays for a doomed network attempt, and a stale driver on PATH is used even after a warning. One more detail: the compatibility warning ends with "currently, chromedriver is recommended for chrome 153.*", with the version blank because discovery had failed.

Waits, stale elements, screenshots and BiDi

Check (Python, local chromedriver 153)Observed
driver.get() of the local page0.091 s
100 iterations of find_element plus .text11.6 ms per pair (two HTTP round trips)
Click, then find #done with no waitNoSuchElementException after 0.008 s
WebDriverWait(d, 5) with presence_of_element_locatedReturned "3 orders" after 1.536 s
implicitly_wait(5), then find_elementReturned "3 orders" after 1.549 s
find_elements for a missing id with a 5 s implicit waitEmpty list, but only after 5.04 s: implicit waits slow down every "is it absent?" check
Implicit 5 s mixed with a 2 s explicit wait on a missing elementTimeoutException after 5.02 s, not 2 s. This is the behaviour the docs warn about ("Do not mix implicit and explicit waits")
Keep a reference to the first list item, re-render the list, read .textStaleElementReferenceException: "stale element reference: stale element not found in the current frame"; re-finding by locator returned "Order #1"
set_window_size(1280, 800), then save_screenshot15,771-byte PNG in 0.046 s, but 1280×657 pixels: the window size includes browser UI even in new headless mode, so set a viewport size or a --window-size argument if the exact height matters
Element screenshot of the list4,043-byte PNG
enable_bidi = True session start0.53 s; capabilities included a webSocketUrl
driver.script.add_console_message_handlerCaptured info "page loaded", error "demo error from page" and info "orders rendered", in order
add_javascript_error_handler plus a thrown errorCaptured "Uncaught Error: boom from test"
driver.accessibility_snapshot()Tree returned in 0.034 s: document, heading "Orders", two buttons, text, list and textbox "search"
CDP with Chrome 153execute_cdp_cmd("Browser.getVersion", {}) worked, but selenium.webdriver.common.devtools contains only v155, v156, v157 and latest, so from ... import v153 raises ImportError

The CDP row shows the "three most recent Chrome versions" policy in action: BiDi handlers and the raw execute_cdp_cmd passthrough worked with Chrome 153, the typed CDP classes did not. Pinning an older browser pushes code toward BiDi or an older Selenium release.

Selenium Grid standalone

Despite the blocked vendor endpoints, selenium-manager --grid downloaded selenium-server-4.53.0.jar (56,871,442 bytes) from the GitHub release in under a second. Started with chromedriver 153 on PATH and java -jar ... standalone, the server logged "Detected 2 available processors", warned that it could not resolve msedgedriver or geckodriver in offline mode, and still advertised two slots each for Chrome, Edge and Firefox. It reported ready after 8.6 s.

CheckObserved
Remote Chrome session start (3 runs)1.87 s, 1.06 s, 0.83 s, against 0.38 s local
find_element plus .text through the Grid21 to 30 ms per pair, two to three times the local cost
se:cdp capabilityPresent, so the Grid proxies CDP and BiDi connections
Firefox session requestSessionNotCreatedException after 0.35 s: "Unable to obtain: geckodriver". The advertised Firefox slot had no working driver behind it
Java process memory after the runsAbout 169 MB resident

A Grid status page can therefore look healthy while some stereotypes fail at session creation; check /status against the drivers actually installed.

Timings against Playwright on the same page

For a rough comparison, the same page was driven from Node.js 22.23.5 by selenium-webdriver 4.53.0 (with chromedriver 153 and Chrome 153) and by Playwright 1.63.0, both against the same full Chrome 153 binary and against Playwright's default headless shell (Chrome 157). Each round ran five sessions and reports medians; there were two rounds.

Metric (median of 5, round 1 / round 2)Selenium 4.53.0, Chrome 153Playwright 1.63.0, same Chrome 153Playwright 1.63.0, headless shell 157
Launch to ready521 / 405 ms420 / 322 ms264 / 118 ms
Navigate to local page119 / 87 ms83 / 50 ms55 / 24 ms
Find element and read text (per call, 50 calls)11.0 / 9.8 ms2.5 / 2.8 ms3.7 / 2.6 ms
Click, then wait for #done (1,500 ms timer)1,734 / 1,722 ms1,820 / 1,819 ms1,817 / 1,814 ms

The pattern is consistent rather than dramatic. Each Selenium Classic command is an HTTP request to chromedriver, so a locate plus a read is two round trips, roughly 5 ms each on this VM. Playwright, generally understood to keep one persistent connection to the browser, was three to four times quicker per call. Launch time depends more on the browser build than the library: with the same full Chrome the gap was about 100 ms, while Playwright's slimmer headless shell started much faster. On click-and-wait Selenium was about 90 ms faster, probably because Playwright's click runs actionability checks first. Where waiting on the application dominates, these differences matter mainly for chatty tests that read many values one by one.

How Selenium compares

Facts come from each project's README and the npm registry on 19 November 2026; "best fit" is a cautious summary.

ToolApproach (per its README)LanguagesLicence, latest releaseBest fit
SeleniumW3C WebDriver client plus WebDriver BiDi; vendor drivers; Grid for remote executionJava, Python, JavaScript, Ruby, C#; Kotlin via JavaApache-2.0; 4.53.0 (17 November 2026)Polyglot teams, standards-based cross-browser testing including Safari, self-hosted grids and existing Selenium suites
Playwright"Drives Chromium, Firefox, and WebKit with a single API"; test runner with "auto-waiting, and web-first assertions"; browsers installed with npx playwright installNode.js, plus Python, .NET and JavaApache-2.0; 1.65.1 on npm (13 November 2026)New end-to-end suites wanting a bundled runner, tracing and auto-waits; WebKit coverage without a Mac
Puppeteer"JavaScript library which provides a high-level API to control Chrome or Firefox over the DevTools Protocol or WebDriver BiDi"; headless by defaultJavaScript and TypeScriptApache-2.0; 25.18.1 (17 November 2026)Chrome-centric scripting, scraping your own sites, PDF and screenshot jobs
Cypress"Fast, easy and reliable testing for anything that runs in a browser"; generally described as running tests inside the browser alongside the appJavaScript and TypeScriptMIT; 16.3.0 (10 November 2026)Front-end teams testing their own single-page app with an interactive runner
WebdriverIOTest framework running on "WebDriver and WebDriver BiDi as well as Appium"Node.jsMIT; 10.2.0 (6 November 2026)JavaScript teams who want WebDriver semantics with a batteries-included runner, plus mobile via Appium

Language and infrastructure usually decide, not raw speed. Selenium alone here has first-party Ruby and C# bindings, and it uses the W3C protocol vendors implement themselves, so Safari support comes from Apple's safaridriver. Playwright and Cypress bundle runners, retries and trace viewers, which Selenium leaves to pytest, JUnit or NUnit. For component-level UI checks, a tool such as Storybook catches problems before a full browser flow is needed, and Selenium then covers the integrated application, for example an API and pages served by Express. Lighthouse covers a separate job, auditing load performance and accessibility.

Limits and when not to use it

  • Driver and browser drift is still your problem in restricted networks. Selenium Manager fixes version matching only when it can reach vendor endpoints. In the hands-on, a stale chromedriver on PATH was used despite a warning, and with no network every session paid for a failed lookup. Pin drivers in CI images or use mirrors and offline mode.
  • Telemetry is on by default. Selenium Manager sends usage data to Plausible unless SE_AVOID_STATS=true or avoid-stats = true is set; in one run without it, the debug log showed an attempt to post to plausible.io/api/event.
  • No built-in test runner, auto-wait or reporting. Synchronisation is your code's job, and the docs call race conditions "one of the primary causes of flaky tests". The mixed-wait run above turned a 2 s timeout into 5 s.
  • Chatty commands cost round trips. About 10 to 12 ms per locate-and-read locally and 21 to 30 ms through Grid on a 2 vCPU VM; batch work in execute_script when looping over many elements.
  • CDP access is tied to recent Chrome. Only the three newest CDP versions are generated. With Chrome 153, Selenium 4.53.0's typed CDP classes were missing. The docs call CDP access temporary and point to BiDi, whose high-level APIs are still incomplete in some bindings.
  • Stale element references are by design. Handles do not re-resolve, so re-rendering front ends need helpers that re-find elements by locator.
  • Grid needs care. Java 11 or newer, about 169 MB for a standalone server here, and stereotypes that can advertise browsers without working drivers.
  • Selenium Manager platform gaps. Its docs say 32-bit ARM Linux is unsupported and Edge is unavailable on Linux arm64.
  • API churn at the edges. Minor releases deprecate and remove methods (4.50.0 removed deprecated Firefox profile extension and certificate methods; 4.53.0 deprecates driver.webextension in Python). Read the binding's changelog before upgrading.
  • Not the right tool for load testing, or JavaScript-only teams that want a bundled runner and trace viewer; Playwright or Cypress may fit better.

Release cadence and documentation notes

Selenium releases all bindings in lockstep, with a minor version roughly every two to five weeks. PyPI shows fourteen releases in 2026 up to 19 November, from 4.40.0 (18 January) to 4.52.0 (29 October) and 4.53.0 (17 November). The Ruby changelog carries the same dates for 4.52.0 and 4.53.0. Nearly every release bumps the supported CDP versions by one, so upgrading in step with Chrome is easier than pinning.

A few inconsistencies turned up while reading the sources and running the code:

  • The Java, Ruby and .NET changelogs for 4.53.0 list both "add the accessibility snapshot atom and the binding methods" and "Remove the accessibility snapshot client implementations". The Python and JavaScript changelogs list only additions, and the installed Python and JavaScript 4.53.0 packages do contain an accessibility snapshot API. Check your own binding's API docs before relying on it.
  • The Selenium Manager docs show a debug log resolving chromedriver 139.0.7258.68, while the paragraph after it describes the downloaded driver as "115, in this example", left over from an older version of the page.
  • Selenium Manager's offline warning prints an empty recommended version, and its versionless fallback URL contains a double slash.
  • The Grid node advertised Edge and Firefox slots on a machine with neither driver installed.

Project activity

Checked 19 November 2026: latest release Selenium 4.53.0 (published 17 November 2026 on PyPI and npm; 4.52.0 preceded it on 29 October 2026), Apache-2.0 licence, 34,598 stars and 8,733 forks on the SeleniumHQ/selenium repository. The repository was created on 14 January 2013, lists Java as its primary language, and develops on trunk, with Python, JavaScript, Ruby and .NET bindings and the Rust-based Selenium Manager in the same Bazel monorepo. PyPI records 238 releases of the Python package going back to April 2008, and npm lists 128 versions of selenium-webdriver. User documentation is published at selenium.dev from the SeleniumHQ/seleniumhq.github.io repository; the main README is aimed at contributors and points users to that manual.

Enjoying this project?

Discover more amazing open-source projects on TechLogHub. We curate the best developer tools and projects.

Project
selenium-browser-automation
Created
November 19
Last Updated
November 19, 2026 at 01:55 PM

Maintain Selenium: W3C WebDriver Browser Automation Toolkit? Add the badge to your README

Show that the project is featured on TechLogHub and send readers to this write-up.

Featured on TechLogHub
[![Featured on TechLogHub](https://techloghub.com/badge-neutral.svg)](https://techloghub.com/open-source/selenium-browser-automation?utm_source=techloghub_badge&utm_medium=referral&utm_campaign=readme)

Find more projects like this

One email a week: new and trending developer tools, fresh comparisons, and what shipped. Unsubscribe in one click.