[🚀 Feature]: ARIA role-based element location - Built this for fun, wondering if it makes sense for Selenium?

[JoanEsquivel]

Description

What would you like Selenium to support or do differently?

Hey! I built something for a personal project and thought I'd share to see if it might be useful for Selenium in general.

What I was trying to solve:
I wanted a more reliable way to select elements in my tests, so I decided to use ARIA roles and accessibility attributes. They're less likely to change compared to classes or IDs, and it also aligns better with how users interact with the app.

What I ended up building:

# I made this work in my local project
username = driver.find_element_by_role("textbox", name="Username")
submit_btn = driver.find_element_by_role("button", name="Submit")
all_buttons = driver.find_elements_by_role("button")

It's been working great for my testing. I used some Chrome DevTools Protocol stuff for the accessibility tree and fell back to DOM parsing when that's not available.

My implementation: https://github.com/JoanEsquivel/python-se/blob/main/tests/test_get_by_role.py

Why I'm posting this:
I'm honestly not sure if this is something that would make sense for Selenium as a whole, or if I'm just solving a problem that's specific to my use case. Maybe other people have better ways of handling this?

I've been using it and it's been solid across Chrome, Firefox, and Edge, but I have no idea what the "right" way to implement something like this in Selenium would be.

Questions I have:

• Is this kind of functionality something Selenium would even want?
• Are there technical reasons this wouldn't work well as a core feature?
• Am I missing some existing way to do this that I just haven't found?

I've never contributed to an open source project before, so I'm not really sure how this works or if this is even the right place to suggest something like this.

Have you considered any alternatives or workarounds?

My implementation:

• Extends WebDriver instances with the new methods
• Uses CDP when available, falls back to DOM parsing
• Handles accessible name resolution (aria-label, aria-labelledby, etc.)
• Has basic type safety with enums

The code is all in my repo: https://github.com/JoanEsquivel/python-se

But honestly, I'm sure there are much better ways to architect this if it were going into Selenium proper. I just hacked together what worked for my needs.

[selenium-ci]

@JoanEsquivel, thank you for creating this issue. We will troubleshoot it as soon as we can.

Selenium Triage Team: remember to follow the Triage Guide

[AtharvaDesai13]

In your testing project, you sought to create a more reliable way to select elements in Selenium by using ARIA roles and accessibility attributes. This is because ARIA roles (like textbox, button, etc.) and accessibility attributes (such as aria-label or aria-labelledby) are often more stable than traditional selectors like IDs or classes. They are also semantically aligned with how users interact with applications, making tests more reflective of actual user behavior.

You successfully built a solution where you extended Selenium to interact with elements based on ARIA roles and accessibility attributes, but you’re now wondering if this feature should be added to Selenium’s core and whether there are any ways to improve the current solution.

Suggested Improvements and Approaches:
Extending WebDriver with Custom Methods:
To improve maintainability and organization, you can extend WebDriver by creating a custom class (e.g., AccessibleWebDriver) to encapsulate the ARIA-based selection methods. This would allow for easy reusability and expansion of functionality in the future. You can add specialized methods such as find_element_by_role and find_elements_by_role, using CSS selectors based on role, aria-label, aria-labelledby, etc.

This custom approach ensures the code is clean and modular while providing flexibility for future enhancements.

Example:

python
class AccessibleWebDriver:
def init(self, driver):
self.driver = driver

def find_element_by_role(self, role, name=None):
    aria_selector = f'[role="{role}"]'
    if name:
        aria_selector += f'[aria-label="{name}"], [aria-labelledby="{name}"]'
    return self.driver.find_element(By.CSS_SELECTOR, aria_selector)

def find_elements_by_role(self, role):
    return self.driver.find_elements(By.CSS_SELECTOR, f'[role="{role}"]')

Use WebDriver Waits for Enhanced Reliability:
To make your element interactions more robust, it's crucial to ensure that elements are available before performing actions. Incorporating WebDriver's explicit waits will allow your test to wait until an element with a specific ARIA role is present, making your tests more reliable, especially when dealing with dynamic content.

Example:

python
Copy
Edit
from selenium.webdriver.support.ui import WebDriverWait
from selenium.webdriver.support import expected_conditions as EC

def wait_for_element_by_role(driver, role, name=None, timeout=10):
aria_selector = f'[role="{role}"]'
if name:
aria_selector += f'[aria-label="{name}"], [aria-labelledby="{name}"]'

return WebDriverWait(driver, timeout).until(
    EC.presence_of_element_located((By.CSS_SELECTOR, aria_selector))
)

Leverage Selenium’s CSS Selectors for ARIA Attributes:
While Selenium doesn’t have a built-in method like find_element_by_role for ARIA roles, you can easily work around this by using CSS selectors to query elements with ARIA attributes directly. For example, you can use role, aria-label, aria-labelledby, and other ARIA attributes in combination with By.CSS_SELECTOR.

Example:

python

driver.find_element(By.CSS_SELECTOR, '[role="textbox"][aria-label="Username"]')
Cross-Browser Compatibility Considerations:
Your solution already works well across Chrome, Firefox, and Edge, which is fantastic. However, make sure to consider fallback logic when using the Chrome DevTools Protocol (CDP), especially in headless environments where the accessibility tree may not always be available. This fallback strategy can prevent failures in browsers that don't fully support CDP or in headless modes.

Incorporate Accessibility Testing Tools:
In addition to improving element selection, integrating accessibility testing tools like axe-core can help you automatically detect accessibility violations in your application. These tools ensure that your app remains accessible to users with disabilities, making your tests not only more reliable but also ensuring better overall quality.

Example using axe-selenium-webdriver:

python
Copy
Edit
from axe_selenium_python import Axe

axe = Axe(driver)
axe.inject()
results = axe.run()
axe.report(results)
Contributing to Selenium:
If you believe that the functionality you’ve built would be beneficial to the broader Selenium community, contributing to the Selenium project could be a great next step. You can start by forking the Selenium repository, making your changes, and submitting a pull request (PR). It would be helpful to open an issue first to discuss your approach with the maintainers and get feedback before diving into the implementation.

Key steps for contributing:

Fork the Selenium repository.

Clone your fork locally and create a new branch for your feature.

Write tests for your new functionality and ensure they pass.

Submit a pull request (PR) and provide a detailed description of your changes, why they’re beneficial, and how to test them.

Alternative Approaches:
Although you are extending Selenium with custom code, you might also want to explore alternatives such as Playwright or Puppeteer, which provide built-in support for more flexible and robust querying. These tools, however, are newer and might not be as widely used as Selenium, so adding this functionality directly to Selenium would certainly fill a useful gap in its feature set.

Conclusion:
Your approach of using ARIA roles and accessibility attributes is a fantastic way to make your tests more stable and reflective of real user interactions. By modularizing your custom logic, leveraging WebDriver waits, and considering fallback strategies for cross-browser compatibility, you can make your solution more maintainable and reliable. Additionally, contributing this feature to the core of Selenium would be a valuable enhancement for the community.

Lastly, integrating automated accessibility testing tools like axe-core can help ensure your app meets accessibility standards, further improving the quality of your tests.

[diemol]

People are overusing ChatGPT for this. Marking the comment above as spam.

[cgoldberg]

Would it be possible to do something similar using BiDi rather than CDP? (using locate_nodes from BrowsingContext)

• https://www.w3.org/TR/webdriver-bidi/#locate-nodes-using-accessibility-attributes
• https://github.com/SeleniumHQ/selenium/blob/trunk/py/selenium/webdriver/common/bidi/browsing_context.py

[cgoldberg]

I've never contributed to an open source project before, so I'm not really sure how this works or if this is even the right place to suggest something like this.

Yes, this is the correct place. For a non-trivial change, the best place to start is a Feature Request for discussion. If people are open to your feature/idea, the next steps would be: fork the repo, create a branch with your changes, create a Pull Request.

For more information on development and contributing, see:

• https://github.com/SeleniumHQ/selenium/blob/trunk/CONTRIBUTING.md
• https://github.com/SeleniumHQ/selenium/blob/trunk/README.md#contributing

For help, you can also join IRC/Slack:

• https://www.selenium.dev/support/#ChatRoom

[JoanEsquivel]

Thanks for your response @cgoldberg I will check the links provided and try BiDi when I have a chance.

[ms6073]

People are overusing ChatGPT for this. Marking the comment above as spam.

This does seem like the lazy man's way of making Selenium work like Playwright!
So for the op, css locators can already do what you mention above. In .NET we would use the following: By.CssSelector("textbox[name='Username']") .

[JoanEsquivel]

Hey, appreciate the input! I agree that CSS selectors are powerful, but this isn't about targeting attributes; it's about accessing the accessibility tree, not the DOM.

The goal here is to use the browsing context.locateNodes BiDi command to query elements the way assistive tech sees them: by role, name, and other semantic properties. It covers things like aria-labelledby, computed names, and actual role mapping, stuff that CSS can’t reach.

I discovered it using Cypress & Playwright, but I thought Selenium could take advantage of the BiDi protocol(initially with CDP, and now using BiDi) :)

[cgoldberg]

css locators can already do what you mention above

Not really.

css selectors can find certain elements, but that is very different than the feature presented here (OP's code already falls back to using css selectors when necessary). This is an interesting way to locate elements via CDP or BiDi without parsing the DOM when possible.