Selenium: Browser Automation Framework & WebDriver
Selenium is the open-source framework behind the W3C WebDriver specification, giving Java, Python, JavaScript, Ruby, C# and Rust code one shared interface for driving Chrome, Firefox and Edge. Reach for it when you need cross-language, low-level control over real browser sessions in CI. Skip it if you want a fast start — this GitHub repo documents contributing and building, not day-one usage; that lives in the separate User Manual.
Understanding Selenium's Core Purpose
Selenium is an umbrella project — a set of tools and libraries, not one binary — built around the W3C WebDriver spec, a browser- and language-neutral protocol for scripting real web browsers. Volunteer contributors maintain it, per the project's README, pairing a Grid component for running sessions with separate client bindings per language. The same automation concept works whether you write it in Java, Python, JavaScript, Ruby, C# or Rust.
Key Aspects of the Selenium Ecosystem
- ✓Implements the W3C WebDriver specification as a platform- and language-neutral protocol, so automation logic isn't tied to one browser's private API.
- ✓Selenium Manager locates browsers and drivers automatically when tests run with --pin_browsers=false, removing manual driver-path configuration.
- ✓Ships separate client bindings for Java, Python, JavaScript, Ruby, C# and Rust — matching the repo's own topic tags — each with its own build path via the ./go <language>:build command.
- ✓The Grid component builds as its own Bazel target (executable-grid), for running sessions across machines rather than a single local browser.
- ✓Headless mode is documented for Chrome, Edge and Firefox via the --headless test flag, for running automation without a visible browser window.
- ✓Tests can be filtered by size — small (no browser), medium, and large (full browser) — so a contributor can run a fast subset instead of the whole suite.
Who This Repository Is For
This particular GitHub repo is for people building or patching Selenium itself, not developers who just want to script a browser. If you're setting up the Bazel toolchain to fix a bug in the Grid or a language binding, or submitting a pull request per CONTRIBUTING.md, you're in the right place. If you only want to write browser tests against an existing Selenium release, the User Manual and your language's Selenium package are the faster path — this repo's own README says as much. For scale, the repo carries 34,349 GitHub stars and 8,694 forks — a fact about maturity, not a verdict on quality.
Setting Up a Selenium Development Environment
All platforms need Bazelisk (a Bazel version wrapper) and Java JDK 17 or greater, with JAVA_HOME pointed at the JDK — not just the JRE. macOS additionally needs the Xcode command-line tools, plus a Rosetta host-platform flag in .bazelrc.local on Apple Silicon. Windows setup is heavier: either a PowerShell script that provisions a full environment, or a manual path through MSYS2, a Visual Studio C++ workload, and registry changes for long file-path support — the README links an older walkthrough it flags as out of date. If you'd rather skip local setup, the repo supports GitPod, a Dev Container (via devcontainer.json), or a Docker image (scripts/dev-image/Dockerfile). Working across multiple git worktrees is a known pain point: Bazel's disk and repository caches are shared via --disk_cache/--repository_cache flags in your home .bazelrc, but each worktree still gets its own output base unless you point --output_base inside the worktree so it's cleaned up automatically.
Common Questions About Selenium
Selenium is licensed under Apache-2.0, according to the repository's license file, so you can use and modify it commercially without copyleft obligations.
Selenium's GitHub topics list dotnet, java, javascript, python, ruby and rust, and the repo's Developing docs cover Java, Python, Ruby and Rust bindings specifically.
Read CONTRIBUTING.md in the SeleniumHQ/selenium repo before opening a pull request; the README also points contributors to set up a full Bazel dev environment first.
Selenium's User Manual lives at selenium.dev/documentation, separate from this GitHub repo's README, which the maintainers say is written for contributors rather than end users.
Selenium builds with Bazel, wrapped by a custom Rake-based ./go command for common tasks like ./go java:install or ./go py:local_dev.
Selenium's test suite documents a --headless flag for running Chrome, Edge and Firefox without a visible UI, per the project's own testing docs.
Strengths
- ✓W3C WebDriver adherence means automation logic is portable across browsers instead of locked to one vendor's private automation API.
- ✓Client bindings for Java, Python, JavaScript, Ruby, C# and Rust, per the repo's own topic tags — not limited to Java despite the project itself being written in it.
- ✓Apache-2.0 license, so it's free to use, modify and redistribute without copyleft obligations.
- ✓Selenium Manager (--pin_browsers=false) automates browser and driver discovery instead of leaving that to manual configuration.
- ✓Multiple ways into a working dev environment — local Bazel setup, GitPod, a Dev Container, or a prebuilt Docker image — instead of only a bare-metal path.
Limitations & risks
- △The GitHub README documents building and contributing, not day-to-day usage — actually writing tests requires the separate User Manual, which isn't part of this repo.
- △The dev toolchain is heavy: Bazelisk, JDK 17+, and on Windows, MSYS2 plus a full Visual Studio C++ workload — considerably more setup than cloning and running one command.
- △The README's own Windows walkthrough links to an external article it calls out of date.
- △Bazel's disk and repository caches grow unbounded, per the README, and multi-worktree setups leak gigabytes of stale output unless you manually configure a per-worktree output base.
- △The test suite ships a --flaky_test_attempts 3 retry flag, which signals that some browser-driven tests aren't reliably deterministic on the first run.
Alternatives
The problem it solves
Before WebDriver became a W3C standard, browser automation scripts were tied to whatever private automation hooks a given browser vendor exposed, so a script written for one browser often didn't port to another. Selenium's specific role is supplying that shared protocol layer — plus client bindings in six languages — so the same automation logic runs against Chrome, Firefox, Edge and other WebDriver-compliant browsers instead of being rewritten per browser.
Best use cases
- •Cross-browser UI test suites that need identical test logic run against Chrome, Firefox and Edge through the same WebDriver interface.
- •End-to-end test automation embedded in an existing test framework, using Selenium's Java, Python, JavaScript, Ruby or C# bindings.
- •Headless test runs in CI, using the --headless flag documented for Chrome, Edge and Firefox.
- •Contributing a fix to Selenium itself — building with Bazel and running the relevant language's test suite locally before opening a pull request.
- •Distributed browser sessions via the Grid component, built as its own Bazel target for running tests across machines.
How to use
This README is explicit that it documents contributing and building, not writing tests against Selenium as a library — that lives in the separate User Manual at selenium.dev/documentation. What it does cover clearly: building with Bazel, either directly (bazel build //java/src/org/openqa/selenium/grid:executable-grid) or through the project's ./go wrapper (./go java:build), and running tests with bazel test, filtered by size (small, medium, large) or by tag (--test_tag_filters=this,-not-this). Useful test flags include --headless for Chrome, Edge and Firefox, --flaky_test_attempts 3 to retry flaky runs, and --test_output streamed to see output as tests run instead of only on failure.
Related repositories
Curious whether selenium is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about selenium.