feat(locator): Resolve Elements with aria-owns and aria-controls as Children in getByRole Method

[phalmeida]

The ariaChildren option was added to the getByRole method in Playwright to enhance the ability to locate elements that are referenced by aria-owns and aria-controls attributes. By default, elements referenced by these attributes are not included in the search. This option allows developers to include these elements in their search.

Why This Solution Was Implemented

ARIA attributes like aria-owns and aria-controls are used to manage relationships between elements for accessibility purposes. Including these elements in the search helps in testing and validating these relationships.
In complex web applications, elements might be referenced by ARIA attributes but not be direct children in the DOM. This option allows for more accurate element selection in such cases.

Example Usage

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>

In this example, the navigation element owns menu1 and menu2 via the aria-owns attribute. To locate the Services menu item, you can use the ariaChildren option.

Code Example

Here is how you can use the ariaChildren option in Playwright:

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');
});

[phalmeida]

@microsoft-github-policy-service agree

[github-actions]

Test results for "tests 1"

8 flaky

⚠️ [chromium-page] › tests/page/page-event-popup.spec.ts:149:3 › should not treat navigations as new popups @chromium-ubuntu-22.04-node18
⚠️ [chromium-page] › tests/page/page-event-request.spec.ts:110:3 › should report navigation requests and responses handled by service worker @chromium-ubuntu-22.04-node20
⚠️ [firefox-page] › tests/page/page-evaluate.spec.ts:403:3 › should throw for too deep reference chain @firefox-ubuntu-22.04-node18
⚠️ [chromium-library] › tests/library/inspector/cli-codegen-java.spec.ts:49:5 › should print the correct context options when using a device @ubuntu-20.04-chromium-tip-of-tree
⚠️ [webkit-library] › tests/library/trace-viewer.spec.ts:238:1 › should show params and return value @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/trace-viewer.spec.ts:1496:1 › should not leak recorders @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/trace-viewer.spec.ts:1664:1 › should toggle canvas rendering @webkit-ubuntu-22.04-node18
⚠️ [webkit-page] › tests/page/page-set-input-files.spec.ts:147:3 › should upload large file @webkit-ubuntu-22.04-node18

37638 passed, 648 skipped
✔️✔️✔️

Merge workflow run.

[yury-s]

Please start with filing a feature request that would provide a rationale for the new API, we have a separate template for it.

[phalmeida]

Feature request: #34348