See @.local/AGENTS.md for additional guidance

Selenium is a Bazel-built monorepo implementing the W3C WebDriver (and related) protocols, shipping multiple language bindings plus Grid and Selenium Manager. The repository README is aimed at contributors; end-user docs live elsewhere.

Invariants (don't violate unless explicitly asked)

• Maintain API/ABI compatibility - users upgrade by changing only version number

• Avoid repo-wide refactors/formatting; prefer small, reversible diffs

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

• 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.

Repo layout

Bindings (see AGENTS.md in each directory for language-specific details):

• Java: java/

• Python: py/

• Ruby: rb/

• JavaScript: javascript/selenium-webdriver/

• .NET: dotnet/

Shared/high-risk areas:

• rust/ (Selenium Manager, see rust/AGENTS.md)

• common/ (build/test wiring; affects multiple areas)

• common/src/ (test HTML fixtures)

• javascript/atoms/ (shared JS atoms; high blast radius)

• scripts/, rake_tasks/, .github/, Rakefile (tooling/build)

• third_party/ treat as read-only

• bazel-*/ treat as generated output

Agent workspace

The .local/ directory (gitignored) is available for generated artifacts or temporary files:

• Use --output_base=.local/bazel-out if bazel output directory restricted

Cross-binding consistency checks

When changing user-visible behavior, compare with at least one other binding:

• Example: rg <term> java/ py/ rb/ dotnet/ javascript/selenium-webdriver/

If behavior is shared/low-level (protocol, serialization, "remote"/transport), suggest follow-up parity work or to file an issue

Testing

When implementing solutions prefer writing a test for it first Prefer small (unit) tests over browser tests for speed/reliability Avoid mocks—they can misrepresent API contracts

Useful flags:

• --test_size_filters=small (unit tests only)

• --test_output=all (display console output)

• --cache_test_results=no (force re-run) See language-specific AGENTS.md for applicable testing usage

Logging

Add logging where users may need insight into what's happening See language-specific AGENTS.md for applicable logging usage

Deprecation policy

This project does not follow semantic versioning (semver); before removing public functionality, mark it as deprecated with a message pointing to the alternative. See language-specific AGENTS.md for applicable deprecation usage

General Guidelines

• Comments should explain why, not what - prefer well-named methods over comments

• PRs should focus on one thing; we squash PRs to default trunk branch

• Prefer copying files to deleting and recreating to maintain git history

• Avoid running bazel clean --expunge

• Run or suggest running ./scripts/format.sh or ./go all:lint before pushing to prevent CI failures

High risk changes (request verification before modifying unless explicitly instructed)

• Everything referenced above as high risk

• WebDriver/BiDi semantics, capability parsing, wire-level behavior

• Dependency updates / MODULE.bazel / repin flows

• Grid routing/distributor/queue logic

After making code changes

• Call out any high risk areas touched

• Note cross-binding impact and any follow-up issues needed