Proposed plan for Selenium 5

[titusfortner]

User description

The purpose of this document is to get all the Selenium devs aligned on both the end result and the principles involved in a Selenium 5 release.

This is smaller in scope than what we have talked about previously, but the most important piece right now is that we get aligned on what we're doing.

This is a PR so we have one place to discuss at a high level what we are doing, and once it is published, so we have a reference to help decide on implementation details.

Feedback is encouraged from all Selenium contributors, and the PR will be merged and referenced as the source of truth when there are sufficient approved reviews from TLC members.

I'm requesting reviews from everyone on TLC and who has been active in #selenium-tlc channel recently.

---

PR Type

Documentation

---

Description

• Proposes Selenium 5 release plan with focused scope

• Defines in-scope items: async APIs, Selenium Manager, BiDi guidelines

• Establishes backwards compatibility and BiDi implementation principles

• Outlines decision-making process via GitHub Issues and TLC meetings

---

Diagram Walkthrough

flowchart LR
  A["Selenium 5 Release Plan"] --> B["In Scope Items"]
  A --> C["Out of Scope Items"]
  A --> D["Principles"]
  B --> B1["Async/Event APIs"]
  B --> B2["Selenium Manager"]
  B --> B3["BiDi Guidelines"]
  D --> D1["Backwards Compatibility"]
  D --> D2["BiDi Implementation"]
  A --> E["GitHub Issues & TLC Decisions"]

Loading

File Walkthrough

Relevant files

Documentation

selenium5-plan.md New Selenium 5 release plan and governance document            proposals/selenium5-plan.md Introduces comprehensive Selenium 5 release plan document Defines in-scope requirements: async/event APIs, Selenium Manager stable API, BiDi cross-bindings guidelines Specifies out-of-scope items: full BiDi implementation, CDP deprecation, major breaking changes Establishes backwards compatibility principle with existing deprecation policy Clarifies BiDi as implementation tool, not public API surface Documents decision-making process using GitHub Issues and TLC meetings +36/-0

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Reconsider strictly hiding BiDi from the API The suggestion proposes reconsidering the decision to hide BiDi as an implementation detail. It recommends exposing BiDi's capabilities through a new, distinct API in Selenium 5 to leverage its full potential. Examples: proposals/selenium5-plan.md [26-31] ### BiDi implementation BiDi is not a new Selenium API, it provides better tools for implementing and extending the existing API - No references to BiDi in the API (casting or namespacing) - Users can access BiDi implementation code, but it is clearly marked as internal usage / likely to change - Enabling BiDi cannot break current Selenium API (requires graceful fallback) - Maintain consistent approach across bindings Solution Walkthrough: Before: ### BiDi implementation BiDi is not a new Selenium API, it provides better tools for implementing and extending the existing API - No references to BiDi in the API (casting or namespacing) - Users can access BiDi implementation code, but it is clearly marked as internal usage / likely to change - Enabling BiDi cannot break current Selenium API (requires graceful fallback) After: ### BiDi implementation BiDi provides better tools for implementing the existing API and also offers new capabilities via a dedicated API. - The existing Selenium API will be implemented using BiDi where possible, without breaking changes. - A new, separate BiDi-specific API will be exposed to allow users to leverage its full power. - This new API will be clearly distinct from the traditional WebDriver API and may evolve independently. Suggestion importance[1-10]: 9 __ Why: This suggestion raises a crucial strategic point about the public API for BiDi, challenging a core principle of the Selenium 5 plan and potentially shaping the future of the library.	High
General	Define strategy for features without fallbacks Refine the BiDi implementation principle to handle cases where a graceful fallback is not possible by requiring such features to be explicitly documented and potentially gated as opt-in. proposals/selenium5-plan.md [30] -- Enabling BiDi cannot break current Selenium API (requires graceful fallback) +- Enabling BiDi should not break the current Selenium API. Where possible, a graceful fallback to a non-BiDi implementation must be provided. Features that rely solely on BiDi and lack a fallback must be explicitly documented and potentially gated as opt-in. Apply / Chat Suggestion importance[1-10]: 7 __ Why: This suggestion astutely points out a potential rigidity in the plan. The proposed change introduces a more practical and realistic strategy for BiDi-only features, which is crucial for future development and innovation.	Medium
	Clarify scope of acceptable breaking changes Clarify the scope of acceptable breaking changes by providing examples like Selenium Manager invocation or language version updates, and requiring that they be minimized and clearly documented. proposals/selenium5-plan.md [24] -- Orchestration changes and dependency changes that cannot be deprecated may be acceptable +- Orchestration changes (e.g., how Selenium Manager is invoked) and dependency updates (e.g., minimum required language version) may be acceptable, but should be minimized and clearly documented as breaking changes. Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that the term "acceptable" is ambiguous in the planning document and proposes a more concrete definition with examples, which improves the clarity of the plan.	Low
More

[netlify]

✅ Deploy Preview for selenium-dev ready!

Name	Link
🔨 Latest commit	a4d25ae
🔍 Latest deploy log	https://app.netlify.com/projects/selenium-dev/deploys/694483e30f87570007631420
😎 Deploy Preview	https://deploy-preview-2556--selenium-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[asolntsev]

Maybe I am out of context, but I didn't understand what exactly has changed. Seems like everything said here also was applicable for Selenium 4.

[titusfortner]

@asolntsev good the hope is that this accurately reflects Selenium's approach. I'm trying to make it explicit, instead of assumed. It's slightly harder without Simon having final say on everything by default.
At one point we discussed more backwards incompatible changes, and some of the bidi implementation work needs to be refocused to confirm to the ideas here.

[bonigarcia]

I have a proposal for Selenium 5: remove support for Page Factory. To my knowledge, this is implemented only in the Java bindings, in the package org.openqa.selenium.support.PageFactory (@FindBy, @FindAll, @FindBys). We are no longer maintaining this logic, and it is a well-known cause of flakiness in Selenium tests. I wrote the following about Page Factory in my Selenium Java book published in 2022 (still true in 2026):

The Page Factory approach is only recommended when the web page tested with Selenium WebDriver is static. This approach can lead to undesirable effects such as stale web elements (i.e., old or no-longer-available elements) when using dynamic web pages.

In the last few months, I've participated in research analysing the source of flakiness in Selenium tests. The results are not published yet, but we have discovered that using this pattern leads to flaky tests when web pages are rendered dynamically (which, in most real cases, always happens).

All in all, I strongly recommend removing this logic from the upcoming Selenium Java releases. Since it is a breaking change, a good time to do it is with Selenium 5.

[diemol]

Removing the page factory for the Selenium 5 release would create several problems for many users, potentially leading to them staying with Selenium 4. If we want to remove Page Factory, the first natural step would be to deprecate it, and then, most likely, build a tool to help users migrate out of the Page Factory to a more reliable structure.

The other approach is to find the issues in the page factory and fix them, but other approaches work much better. I believe we don't have the time and resources to improve Page Factory.

[titusfortner]

I think this is the right move for Selenium 5: #16849