AGENTS.md

1<!--
2Guidance for AI agents working in the Selenium monorepo.
3Language-specific details live in respective subdirectories.
4-->
5## Overview
6 
7Selenium is a Bazel-built monorepo implementing the W3C WebDriver (and related) protocols,
8shipping multiple language bindings plus Grid and Selenium Manager.
9The repository README is aimed at contributors; end-user docs live elsewhere.
10 
11### Local contributor customization
12- The `.local/` directory is available for customization, generated artifacts, scratch work, and temporary files. It is ignored by Git except for `.local/README.md`.
13- A contributor may create `.local/AGENTS.md` for personal repo-specific instructions and preferences. Before beginning any task, check whether `.local/AGENTS.md` exists; if it exists, read it with your file-reading tool and apply it as the contributor's local instruction overlay.
14- If `.local/agent/skills/` exists, inspect its `*/SKILL.md` files and treat them as additional user-defined skills.
15 
16## Invariants (don't violate unless explicitly asked)
17- Maintain API/ABI compatibility by default (users upgrade by changing only the version number); public functionality may be removed only after it has gone through the [Deprecation policy](#deprecation-policy) below
18- Avoid repo-wide refactors/formatting; prefer small, reversible diffs
19 
20## Toolchain
21- 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.
22- Rakefile tasks are executed with a bundled jruby wrapped with `go`/`go.bat` and frequently used by CI jobs
23- Prefer targeted Bazel commands; use `bazel query ...` to locate labels before build/test
24 
25## Execution model
26- Use `bazel query` to explore build graph before reading files
27- 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.
28- When the default output directory is restricted or when working in a git worktree, isolate build output with `--output_base`. It is a startup flag, so it goes *before* the command, and anchor it to the worktree root so it resolves the same from any directory: `bazel --output_base="$(git rev-parse --show-toplevel)/.local/output-base" build //...` (not after `build`/`test`/`query`).
29 
30## Repo layout
31Bindings (see `AGENTS.md` in each directory for language-specific details):
32- Java: `java/`
33- Python: `py/`
34- Ruby: `rb/`
35- JavaScript: `javascript/selenium-webdriver/`
36- .NET: `dotnet/`
37 
38Shared/high-risk areas:
39- `rust/` (Selenium Manager, see `rust/AGENTS.md`)
40- `common/` (build/test wiring; affects multiple areas)
41- `common/src/` (test HTML fixtures)
42- `javascript/atoms/` (shared JS atoms; high blast radius)
43- `scripts/`, `rake_tasks/`, `.github/`, `Rakefile` (tooling/build)
44- `third_party/` treat as read-only
45- `bazel-*/` treat as generated output
46 
47## Cross-binding consistency checks
48When changing user-visible behavior, compare with at least one other binding:
49- Example: `rg <term> java/ py/ rb/ dotnet/ javascript/selenium-webdriver/`
50 
51If behavior is shared/low-level (protocol, serialization, "remote"/transport), suggest follow-up parity work or to file an issue
52 
53## Testing
54When implementing solutions prefer writing a test for it first 
55Prefer small (unit) tests over browser tests for speed/reliability
56Avoid mocks—they can misrepresent API contracts
57 
58Useful flags:
59- `--test_size_filters=small` (unit tests only)
60- `--test_output=all` (display console output)
61- `--cache_test_results=no` (force re-run)
62See language-specific AGENTS.md for applicable testing usage
63 
64## Logging
65Add logging where users may need insight into what's happening
66See language-specific AGENTS.md for applicable logging usage
67 
68## Deprecation policy
69This project does not follow semantic versioning (semver); before removing public functionality, mark it as deprecated with a message pointing to the alternative.
70See language-specific AGENTS.md for applicable deprecation usage
71 
72## General Guidelines
73- Comments should explain *why*, not *what* - prefer well-named methods over comments
74- PRs should focus on one thing; we squash PRs to default `trunk` branch
75- Prefer copying files to deleting and recreating to maintain git history
76- Avoid running `bazel clean --expunge`
77- Formatting: 
78  - `./scripts/format.sh` without arguments will run everything similar to running `./go format` but with failure information; With `--pre-commit` flag it only checks staged changes; With `--pre-push` flag it only checks committed changes with trunk.
79  - If `./scripts/format.sh` is already referenced in a pre-commit or pre-push hook, let the hooks handle formatting 
80  - If not, run or suggest `./scripts/format.sh --pre-push` before pushing to avoid CI formatter failures
81 
82## High risk changes (request verification before modifying unless explicitly instructed)
83- Everything referenced above as high risk
84- WebDriver/BiDi semantics, capability parsing, wire-level behavior
85- Dependency updates / `MODULE.bazel` / repin flows
86- Grid routing/distributor/queue logic
87 
88## After making code changes
89- Call out any high risk areas touched
90- Note cross-binding impact and any follow-up issues needed
91 
92## Reviewing pull requests
93See `.github/pr_review.md` for agentic review priorities and scope.
94