Rules Hub
Code Ruleset
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 DOM read can precede the update and report the wrong state.
Objašnjenje (HR)
Good example
| 1 | await expect.element(page.getByRole('region', { name: 'Preview' }).getByRole('img', { name: 'Cover' })).not.toBeInTheDocument(); |
Explanation (EN)
The scoped accessible locator preserves the intended image target and retries through asynchronous rendering.
Objašnjenje (HR)
Notes (EN)
When a test checks asynchronously rendered user-facing UI, use the configured framework's awaited locator matcher and scope it to the same element the old query targeted.
Exceptions / Tradeoffs (EN)
Role queries exclude some hidden or decorative nodes; use a scoped test id/DOM assertion when actual DOM absence rather than accessibility-tree absence is the contract. includeHidden broadens matching and does not generally disambiguate multiple results.