Function: byRole()

byRole(value, relative?): CssLocator

Defined in: packages/core/src/locators/byRole.ts:36

Locate elements by their ARIA role attribute.

To additionally disambiguate two same-role elements by their accessible name, compose with byAriaLabel (verbatim aria-label) on the SAME element via CssLocator.and:

import { byAriaLabel, byRole } from '@atomic-testing/core';
const openButton = byRole('button').and(byAriaLabel('Open'));

Computed accessible names (aria-labelledby / <label> / text content) are not CSS-expressible and are the job of the forthcoming name-aware findByRole (deferred — see #923).

Parameters

value

string

The role value to match.

relative?

LocatorRelativePosition = 'Descendant'

Relative position of the locator. Defaults to 'Descendant'.

Returns

CssLocator

Example

const dialog = byRole('dialog');
const root = byRole('presentation', 'Root');