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