Skip to content

[Feature]: Filtering getByRole locators using accessible descriptions #39932

@nstepien

Description

@nstepien

🚀 Feature Request

Hi,

Just like in Testing Library, I wish I could filter Locators by accessible description.

Example

page.getByRole('alert', { name, description });

page.getByRole('alert', {
  name: 'Upload successful',
  description: 'File "doc-2025.pdf" was uploaded successfully'
});
page.getByRole('alert', {
  name: 'Upload successful',
  description: 'File "report-2026.pdf" was uploaded successfully'
});

page.getByRole('alert', {
  name: 'Invalid file',
  description: 'File "demo.doc" has an invalid file format'
});
page.getByRole('alert', {
  name: 'Invalid file',
  description: 'File "test.pdf" exceeds the file size limit'
});

Motivation

There are instances where pages render multiple elements with the same role and name, like the above examples, and their accessible description is the only meaningful discriminant.

Being able to filter locators by description would also help migrate existing codebases/tests from Testing Library to Playwright (or Vitest's ivya).

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions