Skip to content

[py] Update DesiredCapabilities example to use modern Options API#16295

Merged
cgoldberg merged 5 commits intoSeleniumHQ:trunkfrom
VbhvGupta:patch-1
Sep 8, 2025
Merged

[py] Update DesiredCapabilities example to use modern Options API#16295
cgoldberg merged 5 commits intoSeleniumHQ:trunkfrom
VbhvGupta:patch-1

Conversation

@VbhvGupta
Copy link
Copy Markdown
Contributor

@VbhvGupta VbhvGupta commented Sep 6, 2025 •
edited by qodo-code-review bot
Loading

User description

Related Issues
N/A - This fixes a bug found in the documentation that was not tracked by an issue.

💥 What does this PR do?
https://github.com/SeleniumHQ/selenium/blob/trunk/py/selenium/webdriver/common/desired_capabilities.py#L32-L38
The code example in the DesiredCapabilities docstring was using the deprecated desired_capabilities argument and was missing the new, mandatory options parameter, causing it to fail with a TypeError.

This PR updates the example to use the modern and correct Options-based approach for instantiating a remote driver, ensuring the documentation is accurate and helpful for users.

🔧 Implementation Notes
This is a straightforward documentation update to align the code example with the current API. No other implementation details are relevant.

💡 Additional Considerations
N/A

🔄 Types of changes
Bug fix (backwards compatible)

PR Type

Documentation

Description

  • Update DesiredCapabilities docstring example to use modern Options API

  • Replace deprecated desired_capabilities argument with options parameter

  • Fix capability names to use current W3C standard format

  • Ensure example code runs without TypeError

Diagram Walkthrough

flowchart LR
  A["Old DesiredCapabilities"] --> B["Modern Options API"]
  B --> C["Working Code Example"]
  D["Deprecated Arguments"] --> E["Current Parameters"]
Loading

File Walkthrough
Relevant files
Documentation
desired_capabilities.py
Modernize DesiredCapabilities docstring example                   

py/selenium/webdriver/common/desired_capabilities.py

  • Replace deprecated desired_capabilities argument with options
    parameter
  • Update capability names to W3C standard (platformName, browserVersion)
  • Add proper import for Firefox Options class
  • Restructure example to use modern Options-based approach
 +16/-9   

@VbhvGupta
DOCS: Update DesiredCapabilities example to use modern Options API
b6b0665 
The code example in the DesiredCapabilities docstring was using the deprecated desired_capabilities argument and was missing the mandatory options argument, causing it to fail with a TypeError.

This PR updates the example to use the  correct Options-based approach for instantiating a remote driver.
@CLAassistant
Copy link
Copy Markdown

CLAassistant commented Sep 6, 2025 •
edited
Loading

CLA assistant check
All committers have signed the CLA.

@selenium-ci selenium-ci added the C-py Python Bindings label Sep 6, 2025
@qodo-code-review
Copy link
Copy Markdown
Contributor

qodo-code-review bot commented Sep 6, 2025

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪
🧪 No relevant tests
🔒 No security concerns identified
⚡ Recommended focus areas for review

Possible Inaccurate Capability

The example sets options.browser_version = "10". For Firefox Options this attribute may not be recognized; typically set_capability("browserVersion", "...") is used. Verify the correct way to specify browser version for the chosen Options class.

 
options.set_capability("platformName", "WINDOWS")
options.browser_version = "10"

# Instantiate an instance of Remote WebDriver with the new options.
driver = webdriver.Remote(
    command_executor=selenium_grid_url,
    options=options
)
Platform Name Value

The example uses "WINDOWS" for platformName. W3C values are typically lowercase like "windows". Confirm expected casing/value per Grid and align to avoid mismatches.

 
options.set_capability("platformName", "WINDOWS")
options.browser_version = "10"

# Instantiate an instance of Remote WebDriver with the new options.
Options Class Specificity

Importing Firefox Options while the surrounding docstring is generic to DesiredCapabilities may confuse users of other browsers. Consider clarifying that the example is Firefox-specific or generalize using a browser-agnostic example.

 
from selenium.webdriver.firefox.options import Options

selenium_grid_url = "http://198.0.0.1:4444/wd/hub"

# Create a new Options object for the desired browser.
options = Options()

# Set capabilities on the Options object.
# Note: "platform" and "version" are now "platformName" and "browserVersion".
options.set_capability("platformName", "WINDOWS")
options.browser_version = "10"

# Instantiate an instance of Remote WebDriver with the new options.
driver = webdriver.Remote(
    command_executor=selenium_grid_url,
    options=options
)

@qodo-code-review
Copy link
Copy Markdown
Contributor

qodo-code-review bot commented Sep 6, 2025 •
edited
Loading

PR Code Suggestions ✨

Explore these optional code suggestions:

CategorySuggestion                                                                                                                                    Impact
High-level
Fix Options API and doc alignment

The example mixes a DesiredCapabilities class doc with an Options-based flow and
uses a likely unsupported attribute (options.browser_version), which may still
lead to broken examples. Update it to set all W3C capabilities via
options.set_capability (e.g., options.set_capability("browserVersion", "10"))
and rewrite/remove the lingering DesiredCapabilities ".copy()" note and intro so
the docstring consistently reflects the modern Options-based approach.

Examples:

py/selenium/webdriver/common/desired_capabilities.py [23-48] 
    Use this as a starting point for creating a desired capabilities object for
    requesting remote webdrivers for connecting to selenium server or selenium grid.

    Usage Example::

        from selenium import webdriver
        from selenium.webdriver.firefox.options import Options
        
        selenium_grid_url = "http://198.0.0.1:4444/wd/hub"
        

 ... (clipped 16 lines)

Solution Walkthrough:

Before:

class DesiredCapabilities:
    """...
    Usage Example::

        from selenium.webdriver.firefox.options import Options
        options = Options()
        options.set_capability("platformName", "WINDOWS")
        options.browser_version = "10"
        driver = webdriver.Remote(..., options=options)

    Note: Always use '.copy()' on the DesiredCapabilities object to avoid the side
    effects of altering the Global class instance.
    """
    ...

After:

class DesiredCapabilities:
    """...
    While DesiredCapabilities can be used, the modern approach is to use Browser Options.

    Usage Example::

        from selenium.webdriver.firefox.options import Options
        options = Options()
        options.set_capability("platformName", "WINDOWS")
        options.set_capability("browserVersion", "10")
        driver = webdriver.Remote(..., options=options)

    """
    ...
Suggestion importance[1-10]: 6

__

Why: The suggestion correctly identifies a significant inconsistency where the PR updates the code example to use Options but leaves the surrounding docstring text referring to the old DesiredCapabilities workflow, which is a major flaw for a documentation fix. However, it incorrectly claims options.browser_version is unsupported, as it is a valid property in the Selenium Options API.

Low
Learned
best practice
Use context manager for driver

Use a context manager to ensure the webdriver.Remote session is closed
automatically. This prevents resource leaks in examples and real code.

py/selenium/webdriver/common/desired_capabilities.py [42-45]

-driver = webdriver.Remote(
+with webdriver.Remote(
     command_executor=selenium_grid_url,
     options=options
-)
+) as driver:
+    ...

[To ensure code accuracy, apply this suggestion manually]

Suggestion importance[1-10]: 6

__

Why:
Relevant best practice - Always close or dispose resources using with/try-finally to prevent leaks.

Low
  • Update

@cgoldberg
Copy link
Copy Markdown
Member

cgoldberg commented Sep 7, 2025

Please fix formatting and sign the CLA.

@cgoldberg
Copy link
Copy Markdown
Member

cgoldberg commented Sep 7, 2025

Please also remove the 2 notes in that docstring that are no longer relevant.

(the comment about "platformName" and "browserVersion", and also the one about using copy())

@cgoldberg cgoldberg changed the title DOCS: Update DesiredCapabilities example to use modern Options API [py] Update DesiredCapabilities example to use modern Options API Sep 8, 2025
cgoldberg
cgoldberg approved these changes Sep 8, 2025
View reviewed changes
Copy link
Copy Markdown
Member

@cgoldberg cgoldberg left a comment

Choose a reason for hiding this comment

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

I just made an update to your branch so it uses a w3c compliant platform name.

The example isn't really that relevant to this class, but I guess it's better than the outdated one that was there previously.

@cgoldberg cgoldberg merged commit caca4ff into SeleniumHQ:trunk Sep 8, 2025
1 check passed
@VbhvGupta VbhvGupta deleted the patch-1 branch September 8, 2025 07:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@cgoldberg cgoldberg cgoldberg approved these changes

Assignees

No one assigned

Labels

C-py Python Bindings Review effort 2/5

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@VbhvGupta @CLAassistant @cgoldberg @selenium-ci