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 1 commit 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
1 commit
Select commit
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.

### Classic fallback for BiDi-backed commands — _ADR pending_

@diemol diemol Jun 25, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

This could be an implementation detail of the migration to Selenium 5 ADR.

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

  1. This is too specific of subject. It should be "Partial BiDi implementation support" where we decide what it means to support a remote end that doesn't implement every feature.
  2. One specific issue with the "per command" fallback is that not all commands can switch between classic and bidi depending on what previous commands were sent
  3. This issue is not just about "what if Safaridriver implements BiDi support but not for everything at first" it can also be about supporting older browsers with inicomplete BiDi implementations

The consensus at the 6/25 TLC meeting was that this probably doesn't belong as a blocker or a prerequisite for Selenium 5, and it can be part of the ADR for the Classic Migration.


A defined, cross-binding mechanism for running a supported command over BiDi and falling back to
Classic when BiDi or the browser does not support it. The mechanism is required; migrating every
command is not.

### 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 finalized API — _ADR pending_

A finalized, documented API the bindings invoke, versioned independently of the client.

Comment on lines +20 to +47

@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. Selenium 5 requires the fallback mechanism, not
coverage of every command.

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