Objective: Rank any locator on the strength ladder on sight, write locators that describe what an element IS rather than where it sits, and know why "element not found" is a locator problem until proven otherwise.
⏱ ≈2 h practice unit · Code: copy, paste, practise · English edition — Español · العربية · বাংলা in translation
🧽 The practice business: FreshNest Home Cleaning — a fictional local cleaning company (owner: Maya Torres) invented for this course. Every example and exercise uses FreshNest, so you learn on a complete, realistic business without ever touching a real one.
Before a test can click, type into, or check anything, it has to find it. A locator is the instruction for finding — "the link whose href is /privacy.html", "the button labelled Send". Crucially, a locator is not the element itself: it is a set of directions the browser follows fresh, every time the locator is used. Like describing a friend in a crowd — "the woman in the red coat" works until two people wear red. Tests live or die on how well their locators describe exactly one thing, in a way that survives the page changing cosmetically. If the element moves, good directions still find it; bad directions were memorising the furniture layout.
The source suite's Page Object uses four kinds, and you will meet all four constantly: by element type — page.locator("h1"); by stable attribute — page.locator(`a[href="${href}"]`); by role + visible label, the most human way — page.getByRole("button", { name: text }); and by a precise selector for a form field — page.locator(selector). Notice .first() everywhere: locators often match several elements ("all links"), and the source suites deliberately take the first match rather than crash on ambiguity — a robustness choice for real-world pages.
From most to least trustworthy, the strength ladder runs: role + name → stable attributes (href, id, name, data-testid) → visible text → element type → CSS structure (div > div > span…). Each step down is more brittle than the one above. Structure is the weakest rung because a locator like main > div:nth-child(3) > button breaks when ANY wrapper changes — and wrappers change constantly; a structure locator is a future failure with a date. So when a test fails with "element not found", it is almost never "the test is broken" or "the site is broken" — it is usually a locator whose description stopped matching the page, most often because the page legitimately changed. Professional debugging starts there.
The original worked code for this unit, verbatim, with its line-by-line explanations. Run it against the course practice project (download on the course page).
page.getByRole("button", { name: "Send" })
page.locator('a[href="/privacy.html"]')By role + name: “the Send button.” By stable attribute: “the link pointing at /privacy.html.” Both describe what the element IS, not where it happens to sit.
// 1. By element type
this.mainHeading = page.locator("h1").first();
// 2. By attribute (href)
linkByHref(href: string) {
return this.page.locator(`a[href="${href}"]`).first();
}
// 3. By role + visible label — the most human way
buttonByText(text: string) {
return this.page.getByRole("button", { name: text }).first();
}
// 4. By a precise selector for a form field
field(selector: string) {
return this.page.locator(selector).first();
}From the module's full text.
constructor(page: Page) {
this.page = page;
this.mainHeading = page.locator("h1").first();
}From the module's full text.