Heuristic:SeleniumHQ Selenium Cross Binding Consistency Check
| Knowledge Sources | |
|---|---|
| Domains | Development, Cross_Language, Quality |
| Last Updated | 2026-02-11 23:00 GMT |
Overview
When changing user-visible behavior, compare the implementation with at least one other language binding to ensure consistency across Java, Python, Ruby, .NET, and JavaScript.
Description
Selenium ships bindings for five languages (Java, Python, Ruby, .NET, JavaScript), all implementing the same W3C WebDriver protocol. User-visible changes in one binding must be consistent with others to prevent cross-language behavior drift. The AGENTS.md explicitly mandates cross-binding comparison and suggests follow-up parity work for shared/low-level changes (protocol, serialization, transport).
Usage
Apply this heuristic before submitting any pull request that changes user-visible behavior, error messages, capability handling, or wire-level protocol behavior. It is critical for changes to shared areas like `common/`, `javascript/atoms/`, and protocol serialization.
The Insight (Rule of Thumb)
- Action: Run `rg <term> java/ py/ rb/ dotnet/ javascript/selenium-webdriver/` to compare implementations across bindings.
- Value: Prevents cross-language behavior drift and user confusion.
- Trade-off: Requires familiarity with multiple language codebases; may need follow-up issues for parity work.
- Scope: Especially critical for protocol, serialization, remote/transport, and capability parsing changes.
Reasoning
The Selenium monorepo's AGENTS.md states: "When changing user-visible behavior, compare with at least one other binding." This is because Selenium users often switch between language bindings (e.g., a team using both Java and Python), and inconsistent behavior creates confusion and distrust. Shared/low-level changes (protocol, serialization) have high blast radius and require explicit follow-up parity work or issue filing.
Code Evidence
AGENTS.md cross-binding check from `AGENTS.md:44-48`:
## 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
High-risk areas from `AGENTS.md:76-80`:
## High risk changes (request verification before modifying)
- WebDriver/BiDi semantics, capability parsing, wire-level behavior
- Dependency updates / MODULE.bazel / repin flows
- Grid routing/distributor/queue logic