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).
Prefer built-in library APIs over hand-rolled workarounds, and verify a feature is truly missing first
Confirm a library lacks a feature (check the real API name) before writing a custom workaround; prefer built-in matchers/utilities over bespoke logic.
Bad example
| 1 | // "the test runner doesn't have a viewport matcher", so we hand-roll one |
| 2 | function isInViewport(el: Element): Promise<boolean> { |
| 3 | return new Promise((resolve) => { |
| 4 | const io = new IntersectionObserver(([entry]) => { |
| 5 | io.disconnect(); |
| 6 | resolve(entry.isIntersecting); |
| 7 | }); |
| 8 | io.observe(el); |
| 9 | }); |
| 10 | } |
| 11 |
|
| 12 | expect(await isInViewport(element)).toBe(true); |
Explanation (EN)
A custom matcher is added based on an unverified assumption that the framework lacks one — but the real matcher exists under a slightly different name. The bespoke implementation is extra code to maintain, easy to get subtly wrong, and duplicates what the library already does.
Objašnjenje (HR)
Dodan je prilagodeni matcher na temelju neprovjerene pretpostavke da ga okvir nema, no pravi matcher postoji pod malo drugacijim imenom. Vlastita implementacija je dodatni kod za odrzavanje, lako se suptilno pogrijesi i duplicira ono sto biblioteka vec radi.
Good example
| 1 | // Verified the real API name in the docs first |
| 2 | await expect.element(element).toBeInViewport(); |
Explanation (EN)
Use the framework's own matcher after confirming its real name in the documentation. If the matcher genuinely did not exist, fall back to the same primitive the library uses internally rather than inventing a different mechanism.
Objašnjenje (HR)
Koristi vlastiti matcher okvira nakon sto si potvrdio njegovo pravo ime u dokumentaciji. Ako matcher stvarno ne bi postojao, posegni za istim primitivom koji biblioteka koristi interno, umjesto da izmisljas drugaciji mehanizam.
Exceptions / Tradeoffs (EN)
Hand-rolling is justified only after confirming the library truly lacks the capability; even then, build on the same underlying primitive the library would use and document why.
Iznimke / Tradeoffi (HR)
Vlastita izrada opravdana je tek nakon sto potvrdis da biblioteka stvarno nema tu mogucnost; cak i tada gradi na istom temeljnom primitivu koji bi biblioteka koristila i dokumentiraj zasto.