[Feature]: Resolve Elements with aria-owns and aria-controls as Children in getByRole Method

[phalmeida]

🚀 Feature Request

We propose adding a feature to the getByRole method in Playwright to include an ariaChildren option. This option would allow developers to locate elements referenced by ARIA attributes like aria-owns and aria-controls, even when these elements are not direct children in the DOM.

Proposed Solution:
Introduce an ariaChildren option to the getByRole method. When enabled, this option will include elements referenced by ARIA attributes in the search scope.

Example

Consider the following DOM structure:

<div role="navigation" aria-owns="menu1 menu2">
  <div id="menu1" role="menu">
    <div role="menuitem">Home</div>
    <div role="menuitem">About</div>
  </div>
</div>
<div id="menu2" role="menu">
  <div role="menuitem">Services</div>
  <div role="menuitem">Contact</div>
</div>

Using the ariaChildren option, developers can locate elements like this:

import { test as it, expect } from './pageTest';

it('should handle aria-children with elements outside the parent tree', async ({ page }) => {
  await page.setContent(`
    <div role="navigation" aria-owns="menu1 menu2">
      <div id="menu1" role="menu">
        <div role="menuitem">Home</div>
        <div role="menuitem">About</div>
      </div>
    </div>
    <div id="menu2" role="menu">
      <div role="menuitem">Services</div>
      <div role="menuitem">Contact</div>
    </div>
  `);

  const menuItem = page.getByRole('navigation').getByRole('menuitem', { name: 'Services', ariaChildren: true });
  await expect(menuItem).toHaveText('Services');
});

Motivation

Currently, elements referenced by aria-owns or aria-controls attributes are not included in the search scope by default. Without this functionality, it becomes challenging to test and validate these relationships effectively.

[yury-s]

We discussed this proposal during our team meeting today. While we see the value in enhancing the getByRole method to account for ARIA relationships, we decided that we are not ready to change the current behavior of locators to expand beyond the DOM tree and consider the ARIA tree at this time.

That said, we will keep this request open for future consideration as we revisit this area. In the meantime, we recommend exploring the toHaveAriaSnapshot method, which may help in validating ARIA relationships and structures more effectively for your scenario.

[phalmeida]

We discussed this proposal during our team meeting today. While we see the value in enhancing the getByRole method to account for ARIA relationships, we decided that we are not ready to change the current behavior of locators to expand beyond the DOM tree and consider the ARIA tree at this time.

That said, we will keep this request open for future consideration as we revisit this area. In the meantime, we recommend exploring the toHaveAriaSnapshot method, which may help in validating ARIA relationships and structures more effectively for your scenario.

@yury-s Thanks for suggesting to use the toHaveAriaSnapshot method. While it’s helpful, we believe it’s better suited for unit testing, which is not our focus here. What we are focus for is to give developers the ability to perform complete end-to-end (E2E) tests. This means they need to interact directly with elements that are considered children in the accessibility tree. The snapshot method does not achieve this goal since it loss the continuity needed for E2E testing. The ariaChildren feature is more recommended for E2E tests and does not break any current behavior. It’s safe because it is only activated when the flag is enabled. Adding this option would improve Playwright by supporting scenarios where developers want to build tests based on the accessibility tree, which aligns with the purpose of the getByRole method. This feature would not add complexity or extra costs to Playwright. At Philips, we are strongly focused on accessibility and committed to keeping this feature updated. We have over 200 developers working on accessibility E2E tests, and they are all waiting for this functionality. We don’t want to create a custom plugin for this because we believe it would be much more valuable as part of Playwright itself. Please consider adding this feature. It would not only help us but also benefit the wider developer community by enabling better accessibility testing with Playwright.

[alexgwolff]

TL;DR: Justification for ariaChildren Feature Request in Playwright

PR: https://github.com/microsoft/playwright/pull/34334

Proposal Summary

The request suggests adding an ariaChildren option to the getByRole method in Playwright. This feature would allow locating elements referenced by ARIA attributes like aria-owns and aria-controls, even when they are not direct DOM children.

Why It Matters

• Aligns with Playwright’s goal of robust accessibility testing. • Enhances support for E2E accessibility scenarios.

Current Playwright Team Position

The team acknowledges the value but is not ready to extend the getByRole behavior to the ARIA tree. They recommended using the toHaveAriaSnapshot method as a workaround.

Key Arguments from Requestor

• E2E Testing Focus: The snapshot method suits unit tests but lacks the continuity required for end-to-end (E2E) testing, which involves direct interaction with elements in the accessibility tree.

• Non-Disruptive: The feature does not alter existing behavior, as it is opt-in via a flag. • Community Benefit: This functionality supports accessibility testing at scale and eliminates the need for custom plugins, benefiting the broader developer community. • Implementation Readiness: A pull request (PR) is already open, implementing this feature and making it ready for review. • Supported by large-scale accessibility efforts, such as Philips’ 200+ developers focused on such tests.

Recommendation

Reconsider adding ariaChildren as an optional feature. With an existing PR ready, this enhancement could be integrated efficiently, providing immediate benefits for accessibility testing while keeping Playwright’s core behavior stable.

[rdsants]

I fully agree with these proposed changes—they would be incredibly useful for accessibility testing in our company’s workflows. This feature would save us time and effort while improving our E2E testing capabilities. Looking forward to seeing it implemented!

[wirmoreno]

I totally support this request of changes. In my company we faced the same issue while testing accessibility. It's really common to get into this scenario, and it become a big headach to handle it without a solution like the suggested one

[diegofachinello]

I agree because this feature will significantly enhance automation and address the issues many developers are currently facing.

[thegfmachado]

This is a crucial feature for improving accessibility testing in Playwright. ARIA attributes like aria-owns and aria-controls are essential for creating accessible web apps, but the current getByRole implementation doesn’t account for these relationships. The proposed ariaChildren option would allow developers to test these accessibility features effectively without relying on brittle selectors.

By aligning Playwright's behavior with ARIA semantics, this feature would simplify testing for modern UI patterns and enhance support for accessible development. I strongly recommend prioritizing this enhancement to make Playwright an even better tool for accessibility-focused testing.

[lfcelini-philips]

It’s worth prioritizing! Simplifying how referenced elements are targeted would save time and boost productivity, especially in accessibility-focused projects.

[alschussler]

Very nice! This is a very important feature for enabling using the getByRole locator for accessibility oriented e2e tests. In fact, considering the getByRole locator description The page.getByRole() locator reflects how users and assistive technology perceive the page, this feature would make the locator behave more as described.

[MateusPhilips]

I completely understand the need for this new feature in the getByRole method in Playwright. I've faced similar challenges while developing applications. Adding the ariaChildren option would significantly streamline our processes. This enhancement would help locate elements referenced by ARIA attributes like aria-owns and aria-controls, which are often not direct children in the DOM. With this feature, we could improve our testing accuracy and efficiency.

Thank you for considering this proposal. It could greatly benefit many developers, including myself.

[felipesilvino]

Very nice! This is a very important feature for enabling using the getByRole locator for accessibility oriented e2e tests. In fact, considering the getByRole locator description The page.getByRole() locator reflects how users and assistive technology perceive the page, this feature would make the locator behave more as described.

I completely agree. Moreover, when I use role as a locator, I am already focusing on the semantics of the page, the Accessibility Object Model (AOM), rather than the DOM. Naturally, any association made through aria-* attributes should be considered by default without requiring an additional argument in the getRole locator.

IMO, this behavior should be configurable as an opt-in feature for the whole test project, something like semanticLocators: true, which would reduce the verbosity of needing to explicitly include the proposed ariaChildren argument on every selector.

[pavelfeldman]

There is no need to ddos this with a series of "I agree" messages, please upvote the main issue and that's more than enough. With this amount of supporting comments navigating the essence of the issue is challenging. As all these comments appeared approximately at the same time and are drastically different from a typical user behavior in the issue, I'll hide them.

[pavelfeldman]

The team acknowledges the value but is not ready to extend the getByRole behavior to the ARIA tree. They recommended using the toHaveAriaSnapshot method as a workaround.

That's not quite accurate. We just asked if toHaveAriaSnapshot maybe solves your needs. If is fine if it does not, but let's keep the record straight. Maybe there is a modification of toHaveAriaSnapshot that makes it work for you, we'd like to keep that option open.

Wrt your proposal, chaining is documented as following DOM in Playwright locators. All the locator engines, including accessible ones, css, data test ids, etc. all can be combined into the chains and those chains follow the DOM hierarchy. We could make getByRole special, but it is unclear why you would not want to use getByText or getByTestId for a generic element under the aria-owns.

[phalmeida]

The team acknowledges the value but is not ready to extend the getByRole behavior to the ARIA tree. They recommended using the toHaveAriaSnapshot method as a workaround.

That's not quite accurate. We just asked if toHaveAriaSnapshot maybe solves your needs. If is fine if it does not, but let's keep the record straight. Maybe there is a modification of toHaveAriaSnapshot that makes it work for you, we'd like to keep that option open.

Wrt your proposal, chaining is documented as following DOM in Playwright locators. All the locator engines, including accessible ones, css, data test ids, etc. all can be combined into the chains and those chains follow the DOM hierarchy. We could make getByRole special, but it is unclear why you would not want to use getByText or getByTestId for a generic element under the aria-owns.

Thank you for the suggestion, but our focus is to use getByRole because it emphasizes semantics and accessibility. This ensures the application is accessible by recognizing elements based on their semantic roles, regardless of text or IDs. This way, we avoid errors from text or ID changes and cover various accessibility scenarios, ensuring compliance with accessibility standards.

[giladv]

not sure how an assertion (toHaveAriaSnapshot) can replace a locator? use case is for example:

1. locate a combobox
2. click on it
3. locate its associated listbox
4. click on one of the options

[alexgwolff]

not sure how an assertion (toHaveAriaSnapshot) can replace a locator? use case is for example:

1. locate a combobox
2. click on it
3. locate its associated listbox
4. click on one of the options

Yes, toHaveAriaSnapshot cannot be used in these cases and many others tests cases.

[alexgwolff]

Any update?

[phalmeida]

Any update?