feat(locator): Add ariaChildren Option to Locator's 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 failed
❌ [chromium-page] › tests/page/selectors-role.spec.ts:421:5 › errors @chromium-ubuntu-22.04-node18
❌ [chromium-page] › tests/page/selectors-role.spec.ts:421:5 › errors @chromium-ubuntu-22.04-node20
❌ [chromium-page] › tests/page/selectors-role.spec.ts:421:5 › errors @chromium-ubuntu-22.04-node22
❌ [firefox-page] › tests/page/selectors-role.spec.ts:421:5 › errors @firefox-ubuntu-22.04-node18
❌ [playwright-test] › tests/runner.spec.ts:118:5 › should ignore subprocess creation error because of SIGINT @macos-latest-node18-1
❌ [playwright-test] › tests/test-step.spec.ts:1420:5 › reading network request / response should not be listed as step @macos-latest-node18-1
❌ [chromium-page] › tests/page/selectors-role.spec.ts:421:5 › errors @ubuntu-20.04-chromium-tip-of-tree
❌ [webkit-page] › tests/page/selectors-role.spec.ts:421:5 › errors @webkit-ubuntu-22.04-node18

10 flaky

⚠️ [firefox-page] › tests/page/page-evaluate.spec.ts:403:3 › should throw for too deep reference chain @firefox-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-trace.spec.ts:341:5 › should work behind reverse proxy @ubuntu-latest-node22-1
⚠️ [webkit-library] › tests/library/browsercontext-clearcookies.spec.ts:92:3 › should remove cookies by domain @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/browsertype-connect.spec.ts:424:5 › launchServer › should reject waitForEvent before browser.onDisconnect fires @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/proxy.spec.ts:93:11 › should proxy local network requests › with other bypasses › localhost @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/trace-viewer.spec.ts:103:1 › should open trace viewer on specific host @webkit-ubuntu-22.04-node18
⚠️ [webkit-library] › tests/library/trace-viewer.spec.ts:1407:1 › should show similar actions from library-only trace @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-page] › tests/page/page-set-input-files.spec.ts:205:3 › should upload multiple large files @webkit-ubuntu-22.04-node18
⚠️ [playwright-test] › tests/ui-mode-test-watch.spec.ts:145:5 › should watch all @windows-latest-node18-1

37628 passed, 648 skipped
✔️✔️✔️

Merge workflow run.