LESSON VIEW
LAB-2 · AUTOMATION PRACTICE LAB · PRACTICAL QA

Locators in Depth

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.

⚡ Key Points

  • A locator is directions, not the thing — re-followed fresh on every use.
  • Describe what the element IS, never where it happens to sit.
  • Strength ladder: role + name → stable attributes → visible text → element type → CSS structure.
  • Structure locators (nth-child chains) break on any wrapper change — a failure with a date.
  • Locators live in exactly one place: the Page Object, usually its constructor.

📖 Read

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.

💻 Code for this unit — copy, paste, practise

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).

B-04 · Example 1 — Locators

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.

B-04 · Example 2 — Locators

// 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.

B-04 · Example 3 — Locators

constructor(page: Page) {
  this.page = page;
  this.mainHeading = page.locator("h1").first();
}

From the module's full text.