Skip to content

[docs] Selenium 5 release charter #17717

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
titusfortner wants to merge 3 commits into
base: trunk
Choose a base branch
from
+73 −0
Open

[docs] Selenium 5 release charter #17717

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
de97f5f
[docs] add Selenium 5 release charter
titusfortner Jun 25, 2026
a683358
[docs] reframe classic fallback as out-of-scope partial BiDi support
titusfortner Jun 26, 2026
5886f13
[docs] clarify Selenium Manager released API scope in charter
titusfortner Jul 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
73 changes: 73 additions & 0 deletions docs/plans/selenium-5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,73 @@
# Selenium 5 Release Charter

- Status: Proposed <!-- Proposed | Accepted | Released | Superseded -->
- Owner: Selenium Technical Leadership Committee (TLC)
- Discussion: <!-- link to this charter's PR -->

## Purpose

Selenium 5 is a focused alignment release: the bindings converge on consistent behavior across
languages. It follows the project's existing deprecation policy — provide a replacement, mark the
old path deprecated, and remove it only after two releases — and is not an occasion for
gratuitous breaking changes.

This document is the index of the decisions that define Selenium 5. Each needs an accepted ADR to
settle its cross-binding design, then implementation in every binding — Java, JavaScript, Python,
Ruby, and .NET — with behavior consistent and implementation idiomatic per language. A decision is
marked _ADR pending_ until its record is accepted, at which point this charter is updated to link
it. An ADR does not name a milestone; this charter records what belongs to Selenium 5.

## Required for release

### BiDi support boundary — _ADR pending_

How the WebDriver BiDi protocol is exposed to users across the bindings. The ADR sets where the
boundary sits between supported Selenium API and internal implementation, and how each binding
marks it.

### Network async/event API — _ADR pending_

The cross-binding API for adding, removing, and clearing handlers for requests, responses, and
authentication.

### Script and logging async/event API — _ADR pending_

The cross-binding API for pinned scripts (pin / unpin / execute) and for console-message,
JavaScript-error, and DOM-mutation handlers.

### Selenium Manager released API — _ADR pending_

Formalize the interface and behaviors required to drop the Beta label and release independently of
the bindings.
Comment on lines +38 to +41

@qodo-code-review qodo-code-review Bot Jul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

1. Selenium manager versioning not specified 📎 Requirement gap ≡ Correctness

The new Selenium Manager released API required item does not state the required independent
Selenium Manager version schema (e.g., starting at 1.0.0-beta1). Without explicitly capturing this
requirement in the charter, the Selenium 5 scope can ship without meeting the versioning compliance
objective.
Agent Prompt 
## Issue description
The Selenium 5 charter section `Selenium Manager released API — ADR pending` does not mention the required independent Selenium Manager version schema (e.g., `1.0.0-beta1`), which is a compliance requirement for Selenium 5.

## Issue Context
The charter is the index of decisions required for Selenium 5; the Selenium Manager decision should explicitly include the independent versioning requirement so the ADR cannot omit it.

## Fix Focus Areas
- docs/plans/selenium-5.md[38-41]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Comment on lines +38 to +41

@qodo-code-review qodo-code-review Bot Jul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

2. --selenium-version flag not required 📎 Requirement gap ≡ Correctness

The new Selenium Manager released API required item does not specify introducing/using a required
--selenium-version flag for telemetry/version reporting, nor that all bindings must pass it. This
risks keeping the existing inferred mapping behavior and inconsistent cross-binding adoption.
Agent Prompt 
## Issue description
The Selenium 5 charter does not record the Selenium Manager requirement to use an explicit `--selenium-version` flag for telemetry/version reporting, nor the requirement that all bindings pass it.

## Issue Context
These are Selenium 5 compliance requirements and should be explicitly captured under the `Selenium Manager released API` ADR scope so the resulting ADR and implementations across bindings cannot omit them.

## Fix Focus Areas
- docs/plans/selenium-5.md[38-41]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Comment on lines +38 to +41

@qodo-code-review qodo-code-review Bot Jul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Informational

4. Ambiguous heading wording 🐞 Bug ⚙ Maintainability

The heading “Selenium Manager released API” is paired with body text describing work needed to “drop
the Beta label,” which mixes present/future state and can mislead readers about whether this is
already released vs. a release goal.
Agent Prompt 
## Issue description
The section title reads as if the API is already released (“released API”), while the description says the purpose is to drop the Beta label and release independently, which reads like future work. This is a clarity/terminology mismatch.

## Issue Context
This is in the Required for release list under Selenium Manager.

## Fix Focus Areas
- docs/plans/selenium-5.md[38-41]

## Suggested fix
Rename the heading to reflect intent (e.g., “Selenium Manager release/GA API” or “Selenium Manager finalized API”), or adjust the body text to clearly indicate this is the target for 5.0 rather than current state.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Comment on lines +20 to +42

@qodo-code-review qodo-code-review Bot Jun 25, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Action required

2. Missing bidi navigation requirement 📎 Requirement gap ≡ Correctness

The charter's "Required for release" list omits BiDi navigation commands and pageLoadStrategy-aware
waiting. This fails to reflect the compliance requirement that BiDi-based navigation be implemented
across bindings with page load strategy respected.
Agent Prompt 
## Issue description
The Selenium 5 release charter does not list BiDi-based navigation (with pageLoadStrategy-aware waiting) as a required-for-release item, even though the compliance checklist mandates it as a minimum viable BiDi module across bindings.

## Issue Context
This document is positioned as the definitive list of decisions/features required for Selenium 5. If navigation is required for release, it should be explicitly listed and tied to the ADR/design work.

## Fix Focus Areas
- docs/plans/selenium-5.md[20-47]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

@titusfortner titusfortner Jun 25, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The intent was to make this part of the ADR for "Classic fallback for BiDi-backed commands" since it is kind of an implementation detail. But agreed, especially if we are going to move that bullet to out of scope (not a requirement for Selenium 5) we need to decide separately if we want to define the mechanism for deciding BiDi vs Classic path for sessions and implement something like Navigation, which Ruby already does.

## Out of scope

These are deferred, not rejected: none blocks Selenium 5.

### Full classic-over-BiDi migration

Routing every classic command through BiDi.

### Partial BiDi implementation support

What it means to support a remote end that does not implement every BiDi feature — choosing the
BiDi or Classic path per session (not every command can switch mid-session), for older browsers or
drivers with incomplete BiDi. Part of the Classic-migration ADR.
Comment on lines +53 to +55

@qodo-code-review qodo-code-review Bot Jul 6, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Informational

3. Undefined adr reference 🐞 Bug ⚙ Maintainability

The “Partial BiDi implementation support” section says it is “Part of the Classic-migration ADR,”
but this charter uses “classic-over-BiDi migration” terminology and the phrase “Classic-migration
ADR” appears nowhere else, making the intended cross-reference unclear.
Agent Prompt 
## Issue description
The charter references a "Classic-migration ADR" that is not defined elsewhere in the document and does not match the surrounding terminology ("classic-over-BiDi migration"), reducing searchability and making future linking ambiguous.

## Issue Context
This is in the Out of scope section under "Partial BiDi implementation support".

## Fix Focus Areas
- docs/plans/selenium-5.md[47-55]

## Suggested fix
Replace “Classic-migration ADR” with terminology that matches the charter section title (e.g., “classic-over-BiDi migration ADR”), and optionally make it an explicit intra-doc link to the “Full classic-over-BiDi migration” section.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Comment on lines +51 to +55

@gsnedders gsnedders Jul 8, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Given there continue to be additions to BiDi, e.g., w3c/webdriver-bidi@54175aaf, it's probably worthwhile defining what counts as partial/incomplete support, because otherwise both Chrome and Firefox are out-of-scope. Even going back to spec changes around a year ago, you'll run into Firefox not supporting the emulation.setScriptingEnabled command, in case that makes it out-of-scope.

That said, I think it should be obvious that support of browsingContext.StartScreencast and emulation.setScriptingEnabled are not really comparable to support of browsingContext.create.

More interestingly would be cases like supporting everything except the emulation module, or supporting only the commands that correspond to Classic ones. Are those out-of-scope?


### DevTools deprecation

Deprecating or removing DevTools (CDP) support.

Comment thread
titusfortner marked this conversation as resolved.
### Convenience layers on the core APIs

Higher-level helpers built on the network and script/event primitives — for example task-oriented
network actions (`mock`, `block`, `redirect`) and one-shot event waiters (`expect_*`).

### Browser context API

A high-level API for managing browsing contexts — for example exposing them as handle objects.

### Capability mapping

High-level APIs over individual BiDi capability modules — permissions, storage, emulation, user
prompts.