Rules Hub
Coding Rules Library
Rule priority, scope & exceptions
Use this to align rules with the senior-level structure (P0/P1/P2, scope, exceptions/tradeoffs).
Assert element presence with retryable accessibility locators, not document.querySelector
In component/browser-mode tests, check for an element's presence or absence with a retryable accessibility locator (`await expect.element(page.getByRole(...)).toBeInTheDocument()` / `.not.toBeInTheDocument()`) instead of a one-shot `document.querySelector(...)` read. The role query mirrors how users and assistive tech find elements, and the awaited matcher waits for the DOM to settle. Only reach for a more specific query (e.g. getByRole with a name, or includeHidden) when several elements share the same role.
Bad example
| 1 | expect(document.querySelector('#panel img')).toBeNull(); |
Explanation (EN)
A one-shot raw DOM query that neither retries nor reflects how the element is exposed to users; a wrong/renamed selector also passes silently.
Objašnjenje (HR)
Good example
| 1 | await expect.element(page.getByRole('img')).not.toBeInTheDocument(); |
Explanation (EN)
A retryable, role-based assertion that waits for the DOM to settle and matches how the element is actually exposed.
Objašnjenje (HR)
Notes (EN)
When multiple elements share a role (e.g. a decorative fallback svg that also exposes role img), disambiguate with getByRole(role, { name }) or includeHidden rather than dropping back to querySelector.