@delorenj/pjangler 1.2.25 → 1.2.33

package/templates/commonproject/_bmad/bmm/testarch/knowledge/selector-resilience.md

@@ -1,527 +0,0 @@
-# Selector Resilience
-
-## Principle
-
-Robust selectors follow a strict hierarchy: **data-testid > ARIA roles > text content > CSS/IDs** (last resort). Selectors must be resilient to UI changes (styling, layout, content updates) and remain human-readable for maintenance.
-
-## Rationale
-
-**The Problem**: Brittle selectors (CSS classes, nth-child, complex XPath) break when UI styling changes, elements are reordered, or design updates occur. This causes test maintenance burden and false negatives.
-
-**The Solution**: Prioritize semantic selectors that reflect user intent (ARIA roles, accessible names, test IDs). Use dynamic filtering for lists instead of nth() indexes. Validate selectors during code review and refactor proactively.
-
-**Why This Matters**:
-
-- Prevents false test failures (UI refactoring doesn't break tests)
-- Improves accessibility (ARIA roles benefit both tests and screen readers)
-- Enhances readability (semantic selectors document user intent)
-- Reduces maintenance burden (robust selectors survive design changes)
-
-## Pattern Examples
-
-### Example 1: Selector Hierarchy (Priority Order with Examples)
-
-**Context**: Choose the most resilient selector for each element type
-
-**Implementation**:
-
-```typescript
-// tests/selectors/hierarchy-examples.spec.ts
-import { test, expect } from '@playwright/test';
-
-test.describe('Selector Hierarchy Best Practices', () => {
-  test('Level 1: data-testid (BEST - most resilient)', async ({ page }) => {
-    await page.goto('/login');
-
-    // ✅ Best: Dedicated test attribute (survives all UI changes)
-    await page.getByTestId('email-input').fill('user@example.com');
-    await page.getByTestId('password-input').fill('password123');
-    await page.getByTestId('login-button').click();
-
-    await expect(page.getByTestId('welcome-message')).toBeVisible();
-
-    // Why it's best:
-    // - Survives CSS refactoring (class name changes)
-    // - Survives layout changes (element reordering)
-    // - Survives content changes (button text updates)
-    // - Explicit test contract (developer knows it's for testing)
-  });
-
-  test('Level 2: ARIA roles and accessible names (GOOD - future-proof)', async ({ page }) => {
-    await page.goto('/login');
-
-    // ✅ Good: Semantic HTML roles (benefits accessibility + tests)
-    await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
-    await page.getByRole('textbox', { name: 'Password' }).fill('password123');
-    await page.getByRole('button', { name: 'Sign In' }).click();
-
-    await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
-
-    // Why it's good:
-    // - Survives CSS refactoring
-    // - Survives layout changes
-    // - Enforces accessibility (screen reader compatible)
-    // - Self-documenting (role + name = clear intent)
-  });
-
-  test('Level 3: Text content (ACCEPTABLE - user-centric)', async ({ page }) => {
-    await page.goto('/dashboard');
-
-    // ✅ Acceptable: Text content (matches user perception)
-    await page.getByText('Create New Order').click();
-    await expect(page.getByText('Order Details')).toBeVisible();
-
-    // Why it's acceptable:
-    // - User-centric (what user sees)
-    // - Survives CSS/layout changes
-    // - Breaks when copy changes (forces test update with content)
-
-    // ⚠️ Use with caution for dynamic/localized content:
-    // - Avoid for content with variables: "User 123" (use regex instead)
-    // - Avoid for i18n content (use data-testid or ARIA)
-  });
-
-  test('Level 4: CSS classes/IDs (LAST RESORT - brittle)', async ({ page }) => {
-    await page.goto('/login');
-
-    // ❌ Last resort: CSS class (breaks with styling updates)
-    // await page.locator('.btn-primary').click()
-
-    // ❌ Last resort: ID (breaks if ID changes)
-    // await page.locator('#login-form').fill(...)
-
-    // ✅ Better: Use data-testid or ARIA instead
-    await page.getByTestId('login-button').click();
-
-    // Why CSS/ID is last resort:
-    // - Breaks with CSS refactoring (class name changes)
-    // - Breaks with HTML restructuring (ID changes)
-    // - Not semantic (unclear what element does)
-    // - Tight coupling between tests and styling
-  });
-});
-```
-
-**Key Points**:
-
-- Hierarchy: data-testid (best) > ARIA (good) > text (acceptable) > CSS/ID (last resort)
-- data-testid survives ALL UI changes (explicit test contract)
-- ARIA roles enforce accessibility (screen reader compatible)
-- Text content is user-centric (but breaks with copy changes)
-- CSS/ID are brittle (break with styling refactoring)
-
----
-
-### Example 2: Dynamic Selector Patterns (Lists, Filters, Regex)
-
-**Context**: Handle dynamic content, lists, and variable data with resilient selectors
-
-**Implementation**:
-
-```typescript
-// tests/selectors/dynamic-selectors.spec.ts
-import { test, expect } from '@playwright/test';
-
-test.describe('Dynamic Selector Patterns', () => {
-  test('regex for variable content (user IDs, timestamps)', async ({ page }) => {
-    await page.goto('/users');
-
-    // ✅ Good: Regex pattern for dynamic user IDs
-    await expect(page.getByText(/User \d+/)).toBeVisible();
-
-    // ✅ Good: Regex for timestamps
-    await expect(page.getByText(/Last login: \d{4}-\d{2}-\d{2}/)).toBeVisible();
-
-    // ✅ Good: Regex for dynamic counts
-    await expect(page.getByText(/\d+ items in cart/)).toBeVisible();
-  });
-
-  test('partial text matching (case-insensitive, substring)', async ({ page }) => {
-    await page.goto('/products');
-
-    // ✅ Good: Partial match (survives minor text changes)
-    await page.getByText('Product', { exact: false }).first().click();
-
-    // ✅ Good: Case-insensitive (survives capitalization changes)
-    await expect(page.getByText(/sign in/i)).toBeVisible();
-  });
-
-  test('filter locators for lists (avoid brittle nth)', async ({ page }) => {
-    await page.goto('/products');
-
-    // ❌ Bad: Index-based (breaks when order changes)
-    // await page.locator('.product-card').nth(2).click()
-
-    // ✅ Good: Filter by content (resilient to reordering)
-    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Premium Plan' }).click();
-
-    // ✅ Good: Filter by attribute
-    await page
-      .locator('[data-testid="product-card"]')
-      .filter({ has: page.locator('[data-status="active"]') })
-      .first()
-      .click();
-  });
-
-  test('nth() only when absolutely necessary', async ({ page }) => {
-    await page.goto('/dashboard');
-
-    // ⚠️ Acceptable: nth(0) for first item (common pattern)
-    const firstNotification = page.getByTestId('notification').nth(0);
-    await expect(firstNotification).toContainText('Welcome');
-
-    // ❌ Bad: nth(5) for arbitrary index (fragile)
-    // await page.getByTestId('notification').nth(5).click()
-
-    // ✅ Better: Use filter() with specific criteria
-    await page.getByTestId('notification').filter({ hasText: 'Critical Alert' }).click();
-  });
-
-  test('combine multiple locators for specificity', async ({ page }) => {
-    await page.goto('/checkout');
-
-    // ✅ Good: Narrow scope with combined locators
-    const shippingSection = page.getByTestId('shipping-section');
-    await shippingSection.getByLabel('Address Line 1').fill('123 Main St');
-    await shippingSection.getByLabel('City').fill('New York');
-
-    // Scoping prevents ambiguity (multiple "City" fields on page)
-  });
-});
-```
-
-**Key Points**:
-
-- Regex patterns handle variable content (IDs, timestamps, counts)
-- Partial matching survives minor text changes (`exact: false`)
-- `filter()` is more resilient than `nth()` (content-based vs index-based)
-- `nth(0)` acceptable for "first item", avoid arbitrary indexes
-- Combine locators to narrow scope (prevent ambiguity)
-
----
-
-### Example 3: Selector Anti-Patterns (What NOT to Do)
-
-**Context**: Common selector mistakes that cause brittle tests
-
-**Problem Examples**:
-
-```typescript
-// tests/selectors/anti-patterns.spec.ts
-import { test, expect } from '@playwright/test';
-
-test.describe('Selector Anti-Patterns to Avoid', () => {
-  test('❌ Anti-Pattern 1: CSS classes (brittle)', async ({ page }) => {
-    await page.goto('/login');
-
-    // ❌ Bad: CSS class (breaks with design system updates)
-    // await page.locator('.btn-primary').click()
-    // await page.locator('.form-input-lg').fill('test@example.com')
-
-    // ✅ Good: Use data-testid or ARIA role
-    await page.getByTestId('login-button').click();
-    await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com');
-  });
-
-  test('❌ Anti-Pattern 2: Index-based nth() (fragile)', async ({ page }) => {
-    await page.goto('/products');
-
-    // ❌ Bad: Index-based (breaks when product order changes)
-    // await page.locator('.product-card').nth(3).click()
-
-    // ✅ Good: Content-based filter
-    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Laptop' }).click();
-  });
-
-  test('❌ Anti-Pattern 3: Complex XPath (hard to maintain)', async ({ page }) => {
-    await page.goto('/dashboard');
-
-    // ❌ Bad: Complex XPath (unreadable, breaks with structure changes)
-    // await page.locator('xpath=//div[@class="container"]//section[2]//button[contains(@class, "primary")]').click()
-
-    // ✅ Good: Semantic selector
-    await page.getByRole('button', { name: 'Create Order' }).click();
-  });
-
-  test('❌ Anti-Pattern 4: ID selectors (coupled to implementation)', async ({ page }) => {
-    await page.goto('/settings');
-
-    // ❌ Bad: HTML ID (breaks if ID changes for accessibility/SEO)
-    // await page.locator('#user-settings-form').fill(...)
-
-    // ✅ Good: data-testid or ARIA landmark
-    await page.getByTestId('user-settings-form').getByLabel('Display Name').fill('John Doe');
-  });
-
-  test('✅ Refactoring: Bad → Good Selector', async ({ page }) => {
-    await page.goto('/checkout');
-
-    // Before (brittle):
-    // await page.locator('.checkout-form > .payment-section > .btn-submit').click()
-
-    // After (resilient):
-    await page.getByTestId('checkout-form').getByRole('button', { name: 'Complete Payment' }).click();
-
-    await expect(page.getByText('Payment successful')).toBeVisible();
-  });
-});
-```
-
-**Why These Fail**:
-
-- **CSS classes**: Change frequently with design updates (Tailwind, CSS modules)
-- **nth() indexes**: Fragile to element reordering (new features, A/B tests)
-- **Complex XPath**: Unreadable, breaks with HTML structure changes
-- **HTML IDs**: Not stable (accessibility improvements change IDs)
-
-**Better Approach**: Use selector hierarchy (testid > ARIA > text)
-
----
-
-### Example 4: Selector Debugging Techniques (Inspector, DevTools, MCP)
-
-**Context**: Debug selector failures interactively to find better alternatives
-
-**Implementation**:
-
-```typescript
-// tests/selectors/debugging-techniques.spec.ts
-import { test, expect } from '@playwright/test';
-
-test.describe('Selector Debugging Techniques', () => {
-  test('use Playwright Inspector to test selectors', async ({ page }) => {
-    await page.goto('/dashboard');
-
-    // Pause test to open Inspector
-    await page.pause();
-
-    // In Inspector console, test selectors:
-    // page.getByTestId('user-menu')              ✅ Works
-    // page.getByRole('button', { name: 'Profile' }) ✅ Works
-    // page.locator('.btn-primary')               ❌ Brittle
-
-    // Use "Pick Locator" feature to generate selectors
-    // Use "Record" mode to capture user interactions
-
-    await page.getByTestId('user-menu').click();
-    await expect(page.getByRole('menu')).toBeVisible();
-  });
-
-  test('use locator.all() to debug lists', async ({ page }) => {
-    await page.goto('/products');
-
-    // Debug: How many products are visible?
-    const products = await page.getByTestId('product-card').all();
-    console.log(`Found ${products.length} products`);
-
-    // Debug: What text is in each product?
-    for (const product of products) {
-      const text = await product.textContent();
-      console.log(`Product text: ${text}`);
-    }
-
-    // Use findings to build better selector
-    await page.getByTestId('product-card').filter({ hasText: 'Laptop' }).click();
-  });
-
-  test('use DevTools console to test selectors', async ({ page }) => {
-    await page.goto('/checkout');
-
-    // Open DevTools (manually or via page.pause())
-    // Test selectors in console:
-    // document.querySelectorAll('[data-testid="payment-method"]')
-    // document.querySelector('#credit-card-input')
-
-    // Find robust selector through trial and error
-    await page.getByTestId('payment-method').selectOption('credit-card');
-  });
-
-  test('MCP browser_generate_locator (if available)', async ({ page }) => {
-    await page.goto('/products');
-
-    // If Playwright MCP available, use browser_generate_locator:
-    // 1. Click element in browser
-    // 2. MCP generates optimal selector
-    // 3. Copy into test
-
-    // Example output from MCP:
-    // page.getByRole('link', { name: 'Product A' })
-
-    // Use generated selector
-    await page.getByRole('link', { name: 'Product A' }).click();
-    await expect(page).toHaveURL(/\/products\/\d+/);
-  });
-});
-```
-
-**Key Points**:
-
-- Playwright Inspector: Interactive selector testing with "Pick Locator" feature
-- `locator.all()`: Debug lists to understand structure and content
-- DevTools console: Test CSS selectors before adding to tests
-- MCP browser_generate_locator: Auto-generate optimal selectors (if MCP available)
-- Always validate selectors work before committing
-
----
-
-### Example 2: Selector Refactoring Guide (Before/After Patterns)
-
-**Context**: Systematically improve brittle selectors to resilient alternatives
-
-**Implementation**:
-
-```typescript
-// tests/selectors/refactoring-guide.spec.ts
-import { test, expect } from '@playwright/test';
-
-test.describe('Selector Refactoring Patterns', () => {
-  test('refactor: CSS class → data-testid', async ({ page }) => {
-    await page.goto('/products');
-
-    // ❌ Before: CSS class (breaks with Tailwind updates)
-    // await page.locator('.bg-blue-500.px-4.py-2.rounded').click()
-
-    // ✅ After: data-testid
-    await page.getByTestId('add-to-cart-button').click();
-
-    // Implementation: Add data-testid to button component
-    // <button className="bg-blue-500 px-4 py-2 rounded" data-testid="add-to-cart-button">
-  });
-
-  test('refactor: nth() index → filter()', async ({ page }) => {
-    await page.goto('/users');
-
-    // ❌ Before: Index-based (breaks when users reorder)
-    // await page.locator('.user-row').nth(2).click()
-
-    // ✅ After: Content-based filter
-    await page.locator('[data-testid="user-row"]').filter({ hasText: 'john@example.com' }).click();
-  });
-
-  test('refactor: Complex XPath → ARIA role', async ({ page }) => {
-    await page.goto('/checkout');
-
-    // ❌ Before: Complex XPath (unreadable, brittle)
-    // await page.locator('xpath=//div[@id="payment"]//form//button[contains(@class, "submit")]').click()
-
-    // ✅ After: ARIA role
-    await page.getByRole('button', { name: 'Complete Payment' }).click();
-  });
-
-  test('refactor: ID selector → data-testid', async ({ page }) => {
-    await page.goto('/settings');
-
-    // ❌ Before: HTML ID (changes with accessibility improvements)
-    // await page.locator('#user-profile-section').getByLabel('Name').fill('John')
-
-    // ✅ After: data-testid + semantic label
-    await page.getByTestId('user-profile-section').getByLabel('Display Name').fill('John Doe');
-  });
-
-  test('refactor: Deeply nested CSS → scoped data-testid', async ({ page }) => {
-    await page.goto('/dashboard');
-
-    // ❌ Before: Deep nesting (breaks with structure changes)
-    // await page.locator('.container .sidebar .menu .item:nth-child(3) a').click()
-
-    // ✅ After: Scoped data-testid
-    const sidebar = page.getByTestId('sidebar');
-    await sidebar.getByRole('link', { name: 'Settings' }).click();
-  });
-});
-```
-
-**Key Points**:
-
-- CSS class → data-testid (survives design system updates)
-- nth() → filter() (content-based vs index-based)
-- Complex XPath → ARIA role (readable, semantic)
-- ID → data-testid (decouples from HTML structure)
-- Deep nesting → scoped locators (modular, maintainable)
-
----
-
-### Example 3: Selector Best Practices Checklist
-
-```typescript
-// tests/selectors/validation-checklist.spec.ts
-import { test, expect } from '@playwright/test';
-
-/**
- * Selector Validation Checklist
- *
- * Before committing test, verify selectors meet these criteria:
- */
-test.describe('Selector Best Practices Validation', () => {
-  test('✅ 1. Prefer data-testid for interactive elements', async ({ page }) => {
-    await page.goto('/login');
-
-    // Interactive elements (buttons, inputs, links) should use data-testid
-    await page.getByTestId('email-input').fill('test@example.com');
-    await page.getByTestId('login-button').click();
-  });
-
-  test('✅ 2. Use ARIA roles for semantic elements', async ({ page }) => {
-    await page.goto('/dashboard');
-
-    // Semantic elements (headings, navigation, forms) use ARIA
-    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
-    await page.getByRole('navigation').getByRole('link', { name: 'Settings' }).click();
-  });
-
-  test('✅ 3. Avoid CSS classes (except when testing styles)', async ({ page }) => {
-    await page.goto('/products');
-
-    // ❌ Never for interaction: page.locator('.btn-primary')
-    // ✅ Only for visual regression: await expect(page.locator('.error-banner')).toHaveCSS('color', 'rgb(255, 0, 0)')
-  });
-
-  test('✅ 4. Use filter() instead of nth() for lists', async ({ page }) => {
-    await page.goto('/orders');
-
-    // List selection should be content-based
-    await page.getByTestId('order-row').filter({ hasText: 'Order #12345' }).click();
-  });
-
-  test('✅ 5. Selectors are human-readable', async ({ page }) => {
-    await page.goto('/checkout');
-
-    // ✅ Good: Clear intent
-    await page.getByTestId('shipping-address-form').getByLabel('Street Address').fill('123 Main St');
-
-    // ❌ Bad: Cryptic
-    // await page.locator('div > div:nth-child(2) > input[type="text"]').fill('123 Main St')
-  });
-});
-```
-
-**Validation Rules**:
-
-1. **Interactive elements** (buttons, inputs) → data-testid
-2. **Semantic elements** (headings, nav, forms) → ARIA roles
-3. **CSS classes** → Avoid (except visual regression tests)
-4. **Lists** → filter() over nth() (content-based selection)
-5. **Readability** → Selectors document user intent (clear, semantic)
-
----
-
-## Selector Resilience Checklist
-
-Before deploying selectors:
-
-- [ ] **Hierarchy followed**: data-testid (1st choice) > ARIA (2nd) > text (3rd) > CSS/ID (last resort)
-- [ ] **Interactive elements use data-testid**: Buttons, inputs, links have dedicated test attributes
-- [ ] **Semantic elements use ARIA**: Headings, navigation, forms use roles and accessible names
-- [ ] **No brittle patterns**: No CSS classes (except visual tests), no arbitrary nth(), no complex XPath
-- [ ] **Dynamic content handled**: Regex for IDs/timestamps, filter() for lists, partial matching for text
-- [ ] **Selectors are scoped**: Use container locators to narrow scope (prevent ambiguity)
-- [ ] **Human-readable**: Selectors document user intent (clear, semantic, maintainable)
-- [ ] **Validated in Inspector**: Test selectors interactively before committing (page.pause())
-
-## Integration Points
-
-- **Used in workflows**: `*atdd` (generate tests with robust selectors), `*automate` (healing selector failures), `*test-review` (validate selector quality)
-- **Related fragments**: `test-healing-patterns.md` (selector failure diagnosis), `fixture-architecture.md` (page object alternatives), `test-quality.md` (maintainability standards)
-- **Tools**: Playwright Inspector (Pick Locator), DevTools console, Playwright MCP browser_generate_locator (optional)
-
-_Source: Playwright selector best practices, accessibility guidelines (ARIA), production test maintenance patterns_