rhdh — Cursor Rules

`typescript // ✅ GOOD - Semantic locators await page.getByRole('button', { name: 'Submit' }).click(); await page.getByLabel('Username').fill('admin'); await page.getByPlaceholder('Search...').type('test'); await expect(page.getByText('Welcome')).toBeVisible(); // ✅ GOOD - Filtering and chaining await page.getByRole('row') .filter({ hasText: 'Guest User' }) .getByRole('button', { name: 'Edit' }) .click(); // ❌ BAD - Using getByText for interactive elements await page.getByText('Submit').click(); // Use getByRole('button', { name: 'Submit' }) instead // ❌ BAD - Implementation-dependent selectors await page.locator('.MuiButton-label').click(); await page.locator('div:nth-child(3)').click(); await page.locator('//*[@id="form"]/div[2]/input').fill('test'); `

• page.getByRole(role, { name }) - Interactive elements, headings (reflects user perception) • page.getByLabel(text) - Form controls with labels • page.getByPlaceholder(text) - Inputs without labels • page.getByText(text) - Non-interactive content only (avoid for buttons/links - use getByRole instead) • page.getByAltText(text) - Images • page.getByTitle(text) - Elements with title attribute • page.getByTestId(id) - When semantic locators unavailable (uses data-testid attribute only) • page.locator(selector) - Avoid CSS/XPath unless necessary

• ❌ CSS class selectors (.MuiButton-label, [class="MuiTableCell"], .MuiDataGrid-) • ❌ Long XPath chains • ❌ nth-child without semantic context • ❌ Using force: true to bypass checks • ❌ Mixing locator strategies inconsistently • ❌ Using getByText for buttons or links (use getByRole instead) • ❌ Targeting dynamically generated text (dynamic status, timestamps) • ❌ Configuring custom test ID attributes (stick with data-testid only) • ❌ Selecting elements without scoping (may match from wrong card/dialog)

Playwright assertions automatically wait and retry (default: 5 seconds) until conditions are met. No manual waits needed. `typescript // ✅ Auto-waiting assertions await expect(page.getByRole('button', { name: 'Submit' })).toBeVisible(); await expect(page.getByLabel('Status')).toHaveText('Submitted'); await expect(page.getByRole('list')).toHaveCount(5); // ❌ Unnecessary manual waiting await page.waitForSelector('.status'); // Don't do this, expect() waits automatically ` Common assertions: toBeVisible(), toBeHidden(), toBeEnabled(), toBeDisabled(), toBeChecked(), toHaveText(), toContainText(), toHaveValue(), toHaveCount(), toHaveAttribute() Auto-checks before actions: Visible, Stable (not animating), Enabled, Editable, Receives Events (not obscured)