Cypress 16.2 Added cy.getByRole. Your Selectors Should Read Like the Page.

Cypress 16.2.0 shipped cy.getByRole() this week. Querying by role and name tests what a user actually sees, and the strict default catches fake buttons your old selectors let through.
Quick answer
Cypress 16.2.0 added cy.getByRole(), which finds elements by ARIA role and accessible name. Using it means your tests check what a user can see and use. By default it only matches native elements, so a div pretending to be a button fails. Keep test IDs for things with no meaningful name, and convert your busiest flows first.
Key takeaways
- cy.getByRole() is built into Cypress 16.2.0, so you no longer need a plugin for role queries.
- Role and name queries fail when a button loses its label or turns into a clickable div. Those are real bugs.
- Keep the strict default. Treat failures on custom components as a bug list, not noise.
- Convert your three busiest flows first and update the rest as you touch them.
Cypress 16.2.0 came out this week with a new query called cy.getByRole(). It finds elements by their ARIA role and accessible name, the way a screen reader would announce them. Until now you needed a plugin for that in Cypress. Now it's built in.
That sounds like a small convenience. I think it's a good reason to look hard at how your team writes selectors, because a lot of suites are full of lookups that test the markup, not the product.
What shipped
From the 16.2.0 release notes and the Cypress changelog:
cy.getByRole('tab', { name: 'Billing' })finds an element by role and, if you want, by its accessible name.- Elements hidden from the accessibility tree are skipped unless you pass
{ hidden: true }. - For roles that have a real HTML element, only that element matches by default. So
cy.getByRole('button')finds a<button>but not a<div role="button">. Pass{ native: false }if you also want elements that only have aroleattribute. - Like
cy.get(), it yields every match and retries until assertions pass. - When nothing matches, the error lists the roles and names that are on the page.
The same release also fixed cy.go(), which had been finishing before the next page loaded. If you have back and forward tests that fail now and then, that fix alone is worth the upgrade.
Why the selector matters
Look at a typical login test:
cy.get('#root > div.auth-wrap > form > div:nth-child(3) > button').click()
Or the slightly better version:
cy.get('[data-cy=submit-btn]').click()
Both pass. Neither tells you whether a person can find and use that button. The first breaks whenever someone moves a div. The second never breaks, even if the button loses its label and turns into an unnamed icon.
Now the role version:
cy.getByRole('button', { name: 'Sign in' }).click()
This line says what a user sees: a button called "Sign in." If a developer swaps the button for a clickable div, the test fails by default. If someone removes the text and leaves a bare icon with no label, the test fails. Those are real bugs for keyboard and screen reader users, and your old selector would have waved them through.
So the test checks the feature and, for free, a small slice of accessibility.
The default is the useful part
I'd keep the default strict matching and resist reaching for { native: false }.
A <div role="button"> needs extra work to behave like a button. It needs a tab stop, Enter and Space handling, and focus styles. Teams often skip some of that. When your test refuses to match it, that's a nudge to ask why the page isn't using a real button.
If you have a lot of custom components, you'll hit failures on day one. Don't treat that as noise. Make a list. Each one is either a quick fix in the component or a deliberate exception you write down.
The error message helps more than it sounds
When a role query finds nothing, Cypress now prints the roles and names it did find. That changes how debugging feels.
With a CSS selector, a miss tells you nothing beyond "not found." You open the DOM, hunt for the element, and work out what changed. With the new error, you might see that the page has a button named "Log in" while your test asked for "Sign in." The copy changed. You know right away whether to update the test or push back on the change.
Where data-cy still makes sense
Role queries aren't right for everything. Keep test IDs for:
- Repeated items with the same name. Ten rows that each have an "Edit" button. Scope to the row first, then use the role inside it.
- Things with no meaningful role. A chart canvas, a drag handle, a status dot.
- Text that changes by locale when you run the same suite in several languages and don't want to keep a copy of every string.
The rule I'd use is simple. If a user can name it, query it by name. If they can't, a test ID is fine.
A plan for an existing suite
Don't rewrite the whole thing in one pull request. That's a week of churn and a review nobody reads.
- Upgrade and change nothing else. Run the suite on 16.2.0 and see what the
cy.go()and other fixes do on their own. - Pick your three busiest flows. Login, checkout, whatever runs most. Convert those selectors to
cy.getByRole(). - Log every failure. Sort them into "the test was wrong," "the copy changed," and "the component has no role or name." The third group is a bug list for your front-end team.
- Add a lint rule or review note so new tests use role queries first.
- Convert the rest as you touch them. Old tests get updated when someone is already editing that spec.
What it won't do
A role query is not an accessibility audit. It won't check colour contrast, focus order, or whether your error messages get announced. It confirms that one element has the role and name you expected. That's useful, and it's narrow.
If accessibility matters to your product, you still want a proper scan in CI and a person tabbing through key flows before release.
My take
Most selector problems come from writing tests against the page's structure instead of what the user sees. cy.getByRole() makes the better habit the easy one. Upgrade, convert one flow this week, and read the failures closely. Some of them will be bugs your users have been working around for months.
Frequently asked questions
It finds elements by their ARIA role and, if you pass one, their accessible name. For example, cy.getByRole('button', { name: 'Sign in' }). It retries like cy.get() and lists the roles and names on the page when nothing matches.


