agentleFS
sayurionishisayurionishi/playwright-scaffold/.claude/skills/selectors/SKILL.md

selectors

Skill1 starsChanged 3 months agoMITView on GitHub

Use when choosing a locator for any element, fixing a strict-mode/locator-not-found error, or adapting locator strategy to the app type (generic, controlled-source, Salesforce). Reads the active profile from PROJECT.md.

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Never guess a selector. Open the live element with playwright-cli (navigate, snapshot, generate_locator) and pick from what's actually in …

    line 12
  2. Very specific:

    Prefer getByRole/getByLabel/stable text.

    line 51
  3. Very specific:

    Add testId?: string to props.

    line 61

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Selectors — Locator Strategy

Locators live in page objects only — never in specs, never in helpers.

Explore before you choose

Never guess a selector. Open the live element with playwright-cli (navigate, snapshot, generate_locator) and pick from what's actually in the DOM. If you can't explore, stop and ASK.

Priority depends on the profile (PROJECT.md)

ProfileOrder
generic (default)getByRole → getByLabel → getByPlaceholder → getByText → getByTestId
controlledgetByTestId → getByRole → getByLabel → getByText
salesforcegetByRole → getByLabel → getByText → getByTestId (+ Lightning notes below)

generic follows Playwright's official guidance (user-facing first). controlled elevates testId because you can add data-testid to the app you own — it's the most stable. Read PROJECT.md to know which is active; if absent, use generic.

Prohibited everywhere (ESLint + review)

page.locator('.btn-primary'); // ❌ CSS class — changes; CSS-modules hash it
page.locator('[class*="control"]'); // ❌ partial-class — only for the loader trap, sparingly
page.locator('//button[1]'); // ❌ XPath — fragile
page.locator('div:nth-child(3)'); // ❌ structural — breaks on DOM change
page.locator('#react-select-3-option'); // ❌ auto-generated id — non-deterministic

Strict mode — one match or be explicit

A locator resolving to >1 element throws. Scope it (modal.getByRole(...)), or add .first()/.last() intentionally. If you wrap a fallback with .or(), tail it with .first() — testId wrappers often contain the fallback text as a child, causing a strict-mode collision.

Salesforce / Lightning notes (salesforce profile)

Load salesforce-locators instead of this section for any real Salesforce work — it carries the full Lightning cookbook (combobox, datatable, modal, toast, record fields) and the strict-mode traps. The summary below is only enough to recognize that you need it.

  • Lightning ids are regenerated per render (input-42) and slds-* classes are a design system, not an API — never select on either.
  • Prefer getByRole/getByLabel/stable text. getByTestId is LAST on this profile: you can't add data-testid to a standard Lightning component (only to a custom LWC you own).
  • Iframes (Visualforce, Classic): page.frameLocator(...), selected by title/name, never by index.
  • Shadow DOM: Lightning defaults to synthetic shadow, not native, so automatic piercing behaves differently than you'd expect. Role/label engines work in both — rely on those.
  • The classic Salesforce strict-mode trap: the highlights panel duplicates detail-panel field values, so a bare getByText('Acme Corp') matches twice. Scope by region — don't reach for .first().

Adding a testId to a controllable component

Add testId?: string to props; render data-testid={testId}. Locate with getByTestId. kebab-case, feature-prefixed, no state encoded (door-status, not door-status-closed).

Checklist

  • Located via the active profile's priority, from real DOM evidence.
  • No CSS-class/XPath/nth-child/auto-id.
  • Resolves to exactly one element (or .first()/.last() is intentional).
  • Declared as a class field in the page object, not inline.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.