Heuristic:SeleniumHQ Selenium Bazel Hermetic Build Requirement
| Knowledge Sources | |
|---|---|
| Domains | Build_System, Development, Best_Practices |
| Last Updated | 2026-02-11 23:00 GMT |
Overview
Always use Bazel commands for building and testing Selenium; never assume local language toolchains are configured or use language-specific build tools (maven, pip, npm) directly.
Description
The Selenium monorepo uses a hermetic Bazel build system that bundles all language toolchains (JDK 17, Node.js 20, Python 3.10+, .NET 8.0, Rust). This ensures reproducible builds regardless of the developer's local environment. Running language-specific tools directly (e.g., `mvn`, `pip install`, `npm test`) bypasses Bazel's dependency management and may produce incorrect results, fail due to missing dependencies, or introduce version mismatches.
Usage
Apply this heuristic every time you build, test, or run any Selenium code. Use `bazel query` to explore the build graph before reading files. Use the `./go` wrapper (or `go.bat` on Windows) for Rakefile tasks. Avoid `bazel clean --expunge` as it destroys the entire cache.
The Insight (Rule of Thumb)
- Action: Use `bazel build` and `bazel test` for all operations; use `bazel query` to find target labels.
- Value: Reproducible builds across all platforms; no "works on my machine" issues.
- Trade-off: Initial build is slower due to toolchain download; subsequent builds are fast due to caching.
- Anti-patterns: Running `mvn test`, `pytest`, `npm test`, or `cargo build` directly outside of Bazel.
Reasoning
The AGENTS.md states: "The project uses Bazelisk with a hermetic Bazel toolset. Do not run tests or execute Selenium code assuming a language-specific local development environment is configured." This is because each binding targets specific toolchain versions (JDK 17, Node 20.9.0, Python 3.10.19, .NET 8.0.203) that may differ from locally installed versions. Bazel ensures exact version matching and dependency resolution.
Code Evidence
AGENTS.md guidance from `AGENTS.md:15-22`:
## Toolchain
- The project uses Bazelisk with a hermetic Bazel toolset. Do not run
tests or execute Selenium code assuming a language-specific local
development environment is configured.
- Rakefile tasks are executed with a bundled jruby wrapped with
`go`/`go.bat` and frequently used by CI jobs
- Prefer targeted Bazel commands; use `bazel query ...` to locate labels
before build/test
Execution model from `AGENTS.md:24-27`:
## Execution model
- Use `bazel query` to explore build graph before reading files
- Attempt to execute Bazel commands directly. If prevented due to
network/toolchain restrictions within the sandbox, fall back to
suggesting copy/paste commands for the user on a separate line.
Useful test flags from `AGENTS.md:55-58`:
Useful flags:
- `--test_size_filters=small` (unit tests only)
- `--test_output=all` (display console output)
- `--cache_test_results=no` (force re-run)