Class: AccessibleRoleLocator
Defined in: packages/core/src/locators/AccessibleRoleLocator.ts:60
A locator that resolves by ARIA role plus the COMPUTED accessible name (the
accname algorithm: aria-labelledby id-refs, an associated <label>,
wrapping/title text, and visible descendant text) — built by findByRole,
never directly.
This is the one locator kind with NO CSS representation: the accessible name
is the output of a multi-node graph traversal that no CSS selector can
express (see ADR-008
and the design in ADR 0001, Decision B).
selector (inherited from CssLocator) is therefore a
human-readable DIAGNOSTIC string only — e.g. role=button name="Save" — for
error messages; it is never run as CSS. Resolution instead happens inside
each interactor, backed by an engine that already implements accname:
@testing-library/dom's queryAllByRole in DOMInteractor, Playwright's
Locator.getByRole/Page.getByRole in PlaywrightInteractor.
name matching is always exact and case-sensitive, in BOTH engines — a
deliberate simplification, not an oversight. @testing-library/dom's
getByRole only supports exact string comparison for a string name (no
substring/fuzzy mode exists in its public API for that case); Playwright's
getByRole defaults to fuzzy substring matching instead. Rather than expose
an exact toggle that only ONE engine could honor — a correctness trap for
a library whose entire contract is "the same suite runs identically in both
environments" — PlaywrightInteractor always passes exact: true,
matching jsdom's only mode.
Composition: an AccessibleRoleLocator MUST be the last (or only) segment
of a PartLocator chain — everything before it resolves normally (by
CSS) to a scope container the accname search runs within; nothing may
follow it (see locatorUtil.splitAtAccessibleRoleLocator). Its
complexity is 'accessibleRole', distinct from 'primitive', so
locatorUtil.and() — same-element CSS compounding — already rejects it via
the same "primitive chains only" guard that rejects a linked locator.
See​
findByRole
Extends​
Constructors​
Constructor​
new AccessibleRoleLocator(
role,initializeValue):AccessibleRoleLocator
Defined in: packages/core/src/locators/AccessibleRoleLocator.ts:63
Parameters​
role​
string
initializeValue​
AccessibleRoleLocatorInitializer & Partial<CssLocatorInitializer>
Returns​
AccessibleRoleLocator
Overrides​
Properties​
role​
readonlyrole:string
Defined in: packages/core/src/locators/AccessibleRoleLocator.ts:64
Accessors​
complexity​
Get Signature​
get complexity():
LocatorComplexity
Defined in: packages/core/src/locators/AccessibleRoleLocator.ts:72
Returns​
Overrides​
name​
Get Signature​
get name():
string|undefined
Defined in: packages/core/src/locators/AccessibleRoleLocator.ts:87
Returns​
string | undefined
relative​
Get Signature​
get relative():
AccessibleRoleLocatorRelativePosition
Defined in: packages/core/src/locators/AccessibleRoleLocator.ts:83
Narrows CssLocator.relative's return type: the constructor only
ever accepts AccessibleRoleLocatorRelativePosition, so every
instance's underlying value is already within that narrower set — this
cast just reflects that guarantee in the type, so clone() doesn't need
one of its own.
Returns​
AccessibleRoleLocatorRelativePosition
Overrides​
Methods​
clone()​
clone(
override?):AccessibleRoleLocator
Defined in: packages/core/src/locators/AccessibleRoleLocator.ts:91
Parameters​
override?​
Partial<AccessibleRoleLocatorInitializer> & Partial<CssLocatorInitializer>
Returns​
AccessibleRoleLocator
Overrides​
Inherited members (1)
Properties​
selector​
readonlyselector:string
Defined in: packages/core/src/locators/CssLocator.ts:22