Selectors

Selector Strategy

Critical

• Selector priority order is mandatory: getByRole > getByLabel > getByPlaceholder > getByText > getByTestId. Move to the next option only when the previous one is not feasible.
• NEVER use XPath (page.locator('//...') or 'xpath=...').
• NEVER use CSS class or ID selectors as the primary strategy (page.locator('.btn-primary'), page.locator('#submit')). Acceptable only as an absolute last resort after ruling out every semantic option.
• Exploration with playwright-cli is mandatory before writing any selectors. No guessing from wireframes, docs, or screenshots. Read the playwright-cli skill for the commands.
• If the app cannot be reached or auth fails, stop and notify the human — never ship placeholder locators with guessed names.
• String values inside getByText(...) come from enums/{area}/* (e.g. Messages.LOGIN_ERROR). Never hardcode repeated UI strings. See the enums skill.
• Every page object covering forms or CRUD must include feedback / validation message selectors — success, error, field validation, toast, loading, empty state as applicable. A page object without them is incomplete.
• Locators are get accessors returning Locator — this is a style/readability convention in the scaffold. Playwright's Locator is lazy, so get and a readonly field set in the constructor behave identically at runtime.

Instructions

Phase 1: Open and authenticate

Never generate selectors from assumptions or documentation alone. Before writing any locators or page objects, explore the live application by running playwright-cli in the terminal (read the playwright-cli skill). Do not use IDE browser MCP, Cursor browser tools, or any substitute — orchestrator rule: No Substitute UI Exploration. If playwright-cli cannot run, stop and notify the human.

playwright-cli open <APP_URL>
playwright-cli snapshot

If the page fails to load or requires authentication:

1. Stop immediately — do not guess selectors or proceed with placeholder locators.
2. Notify the human with the exact issue: "The application at <URL> returned [error/login page/blank screen]. I need [credentials / a different URL / instructions to set up auth state] before I can proceed."
3. Wait for the human to provide remediation (login credentials, storage state file, environment variables, or manual login instructions).
4. After remediation, re-open and verify the page loads correctly before continuing.

Phase 2: Explore like a user

Navigate through the feature under test the way a real user would. At each page/state, take a snapshot and observe:

• Forms — input fields, labels, dropdowns, checkboxes, radio buttons.
• Buttons and CTAs — submit, cancel, delete, edit, create actions.
• Navigation — links, menus, breadcrumbs, tabs.
• Feedback elements — success banners, error messages, validation errors on fields, toast notifications, loading spinners.
• Dynamic content — content that appears after actions (modals, expanded sections, new rows in tables).

playwright-cli snapshot
playwright-cli click <ref>
playwright-cli snapshot

Trigger CRUD operations where possible to discover the actual validation messages and success/error feedback the application displays. Capture the exact text rendered — this will go into enums via the enums skill.

Phase 3: Plan test coverage

Based on what was discovered, draft a test plan covering the critical paths. The plan should identify:

1. Happy paths — the primary successful flows (create, read, update, delete).
2. Validation paths — what happens when required fields are empty, invalid data is submitted, etc.
3. Error paths — server errors, permission denied, resource not found.
4. Edge cases — boundary inputs, concurrent operations, empty states.

If feature documentation exists (user stories, acceptance criteria, design specs), cross-reference it with the discovered UI to ensure coverage is complete.

No human approval is needed for this plan — proceed directly to generating selectors and page objects.

Phase 4: Generate selectors

Now that the real UI is understood, generate selectors using the Priority Order below. Pay special attention to feedback / validation message selectors — these are the most commonly missed.

Priority Order (Mandatory)

Use semantic locators in this order. Move to the next option ONLY when the previous one is not feasible:

1. getByRole() — Accessibility-based. Always the first choice for buttons, links, headings, textboxes, checkboxes, etc.
2. getByLabel() — For form inputs that have associated <label> elements.
3. getByPlaceholder() — For inputs with placeholder text when no label exists.
4. getByText() — For static text content, messages, or non-interactive elements.
5. getByTestId() — Fallback when none of the above produce a reliable locator.

Correct Examples

// 1. getByRole -- buttons, links, headings, navigation
page.getByRole('button', { name: 'Submit' });
page.getByRole('link', { name: 'Dashboard' });
page.getByRole('heading', { name: 'Welcome' });
page.getByRole('navigation');
page.getByRole('textbox', { name: 'Email' });
page.getByRole('checkbox', { name: 'Remember me' });

// 2. getByLabel -- form fields with labels
page.getByLabel('Email');
page.getByLabel('Password');

// 3. getByPlaceholder -- inputs without labels
page.getByPlaceholder('Search...');

// 4. getByText -- static content
page.getByText('Login successful');
page.getByText(Messages.LOGIN_ERROR); // prefer enums for repeated strings

// 5. getByTestId -- last resort
page.getByTestId('user-avatar');

Forbidden (NEVER Use)

• XPath selectors — brittle, unreadable, not accessible.

  // FORBIDDEN
  page.locator('//div[@id="test"]');
  page.locator('xpath=//button[text()="Submit"]');

• CSS selectors for primary strategy — acceptable only as a page.locator() last resort, never as the default approach.

  // AVOID unless absolutely necessary
  page.locator('.btn-primary');
  page.locator('#submit-button');