agent-bober 0.4.3 → 0.5.1

package/skills/bober.playwright/references/playwright-patterns.md

@@ -0,0 +1,377 @@
+# Playwright Best Practices for Bober Projects
+
+This reference document describes patterns and best practices for writing Playwright E2E tests within the bober agent workflow. The generator and evaluator agents should follow these patterns to produce robust, maintainable tests.
+
+---
+
+## Selector Strategy: `data-testid` First
+
+When Playwright is an evaluation strategy, all UI components **must** include `data-testid` attributes on interactive elements and key content areas. This is non-negotiable.
+
+### Why `data-testid`?
+
+- **Stable across refactors.** CSS classes, tag names, and text content change frequently. `data-testid` attributes are explicitly for testing and survive refactors.
+- **No coupling to styling.** Tests do not break when Tailwind classes change or when a component library is swapped.
+- **Clear intent.** A `data-testid` attribute signals "this element is tested" to every developer on the team.
+- **Framework-agnostic.** Works identically in React, Vue, Svelte, and plain HTML.
+
+### Naming Convention
+
+Use descriptive, kebab-case names that describe the element's purpose:
+
+```html
+<!-- Good -->
+<form data-testid="login-form">
+  <input data-testid="email-input" />
+  <input data-testid="password-input" />
+  <button data-testid="login-submit-button">Log In</button>
+  <p data-testid="login-error-message">Invalid credentials</p>
+</form>
+
+<!-- Bad -->
+<form data-testid="form1">
+  <input data-testid="input1" />
+  <button data-testid="btn">Log In</button>
+</form>
+```
+
+### Where to Add `data-testid`
+
+The generator must add `data-testid` to:
+- Forms and form elements (inputs, buttons, selects, textareas)
+- Navigation links and menu items
+- Content containers that display dynamic data (cards, lists, tables)
+- Error messages and status indicators
+- Modal dialogs and their trigger buttons
+- Loading indicators and empty state messages
+
+---
+
+## Test File Structure
+
+### One File Per Feature or Sprint
+
+```
+e2e/
+  auth.spec.ts           # Authentication flows (login, register, logout)
+  dashboard.spec.ts      # Dashboard page tests
+  settings.spec.ts       # Settings page tests
+  auth.setup.ts          # Authentication setup (shared storage state)
+```
+
+### Standard Test Template
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Feature: Dashboard', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/dashboard');
+    await page.waitForLoadState('networkidle');
+  });
+
+  test('displays the dashboard header', async ({ page }) => {
+    const header = page.getByTestId('dashboard-header');
+    await expect(header).toBeVisible();
+    await expect(header).toHaveText(/Dashboard/);
+  });
+
+  test('shows data cards when data is loaded', async ({ page }) => {
+    const cardContainer = page.getByTestId('dashboard-cards');
+    await expect(cardContainer).toBeVisible();
+
+    const cards = page.getByTestId('dashboard-card');
+    await expect(cards.first()).toBeVisible();
+  });
+
+  test('handles empty state gracefully', async ({ page }) => {
+    // If testing empty state, you may need to intercept the API
+    await page.route('**/api/dashboard', (route) =>
+      route.fulfill({ status: 200, json: { items: [] } }),
+    );
+    await page.reload();
+    await page.waitForLoadState('networkidle');
+
+    const emptyState = page.getByTestId('dashboard-empty-state');
+    await expect(emptyState).toBeVisible();
+  });
+});
+```
+
+---
+
+## Common Patterns
+
+### Form Submission
+
+```typescript
+test('submits the registration form', async ({ page }) => {
+  await page.goto('/register');
+
+  await page.getByTestId('name-input').fill('Test User');
+  await page.getByTestId('email-input').fill('test@example.com');
+  await page.getByTestId('password-input').fill('SecurePass123!');
+  await page.getByTestId('register-submit-button').click();
+
+  // Wait for navigation after successful submission
+  await expect(page).toHaveURL(/\/dashboard/);
+
+  // Or wait for a success message
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+### Form Validation
+
+```typescript
+test('shows validation errors for invalid input', async ({ page }) => {
+  await page.goto('/register');
+
+  // Submit empty form
+  await page.getByTestId('register-submit-button').click();
+
+  // Check for validation messages
+  await expect(page.getByTestId('name-error')).toBeVisible();
+  await expect(page.getByTestId('email-error')).toBeVisible();
+  await expect(page.getByTestId('password-error')).toBeVisible();
+});
+```
+
+### Navigation
+
+```typescript
+test('navigates to the settings page', async ({ page }) => {
+  await page.goto('/');
+
+  await page.getByTestId('nav-settings-link').click();
+  await expect(page).toHaveURL(/\/settings/);
+  await expect(page.getByTestId('settings-page')).toBeVisible();
+});
+```
+
+### SPA Route Changes
+
+For single-page applications, use `waitForLoadState('networkidle')` after client-side navigation:
+
+```typescript
+test('client-side navigation works', async ({ page }) => {
+  await page.goto('/');
+  await page.waitForLoadState('networkidle');
+
+  await page.getByTestId('nav-about-link').click();
+  await page.waitForLoadState('networkidle');
+
+  await expect(page).toHaveURL(/\/about/);
+  await expect(page.getByTestId('about-page-content')).toBeVisible();
+});
+```
+
+### API Mocking
+
+Use Playwright's `page.route()` to mock API responses when testing specific UI states:
+
+```typescript
+test('displays error when API fails', async ({ page }) => {
+  // Intercept the API call and return an error
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 500,
+      json: { error: 'Internal Server Error' },
+    }),
+  );
+
+  await page.goto('/users');
+  await page.waitForLoadState('networkidle');
+
+  await expect(page.getByTestId('error-message')).toBeVisible();
+  await expect(page.getByTestId('error-message')).toContainText(/error/i);
+});
+```
+
+### Waiting for API Responses
+
+```typescript
+test('loads user data from API', async ({ page }) => {
+  await page.goto('/users');
+
+  // Wait for the specific API response
+  const response = await page.waitForResponse('**/api/users');
+  expect(response.status()).toBe(200);
+
+  // Then assert on the rendered data
+  await expect(page.getByTestId('user-list')).toBeVisible();
+});
+```
+
+---
+
+## Authentication Handling
+
+### Shared Auth State with `storageState`
+
+For projects requiring authenticated users, create a setup file that logs in once and saves the browser state:
+
+**`e2e/auth.setup.ts`:**
+```typescript
+import { test as setup, expect } from '@playwright/test';
+
+const authFile = 'e2e/.auth/user.json';
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/login');
+
+  await page.getByTestId('email-input').fill('test@example.com');
+  await page.getByTestId('password-input').fill('testpassword');
+  await page.getByTestId('login-submit-button').click();
+
+  // Wait for successful login (redirect to dashboard or similar)
+  await expect(page).toHaveURL(/\/dashboard/);
+
+  // Save the authentication state
+  await page.context().storageState({ path: authFile });
+});
+```
+
+**`playwright.config.ts` additions:**
+```typescript
+projects: [
+  {
+    name: 'setup',
+    testMatch: /auth\.setup\.ts/,
+  },
+  {
+    name: 'chromium',
+    use: {
+      ...devices['Desktop Chrome'],
+      storageState: 'e2e/.auth/user.json',
+    },
+    dependencies: ['setup'],
+  },
+],
+```
+
+Add `e2e/.auth/` to `.gitignore`.
+
+---
+
+## Visual Verification Without Flakiness
+
+Avoid pixel-comparison screenshot tests. They are extremely flaky across different environments (font rendering, anti-aliasing, OS differences). Instead:
+
+### Check Structural Presence
+
+```typescript
+// Good: Check that elements exist and have the right content
+await expect(page.getByTestId('hero-title')).toHaveText('Welcome');
+await expect(page.getByTestId('hero-image')).toBeVisible();
+
+// Bad: Screenshot comparison
+// expect(await page.screenshot()).toMatchSnapshot();
+```
+
+### Check CSS Properties When Needed
+
+```typescript
+// Check that an element has a specific visual state
+const button = page.getByTestId('submit-button');
+await expect(button).toHaveCSS('background-color', 'rgb(37, 99, 235)');
+await expect(button).toBeEnabled();
+```
+
+### Use Failure Screenshots for Debugging Only
+
+The `playwright.config.ts` is configured with `screenshot: 'only-on-failure'`. This captures screenshots when tests fail, which is useful for debugging but does not introduce flaky assertions.
+
+---
+
+## Error Handling in Tests
+
+### Capture Console Errors
+
+```typescript
+test('page has no JavaScript errors', async ({ page }) => {
+  const errors: string[] = [];
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') {
+      errors.push(msg.text());
+    }
+  });
+
+  await page.goto('/dashboard');
+  await page.waitForLoadState('networkidle');
+
+  // Filter out known acceptable errors if needed
+  const criticalErrors = errors.filter(
+    (e) => !e.includes('favicon.ico'),
+  );
+  expect(criticalErrors).toEqual([]);
+});
+```
+
+### Handle Network Failures Gracefully
+
+```typescript
+test('shows offline message when network fails', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForLoadState('networkidle');
+
+  // Simulate network failure
+  await page.route('**/*', (route) => route.abort());
+
+  // Trigger an action that requires network
+  await page.getByTestId('refresh-button').click();
+
+  await expect(page.getByTestId('network-error-message')).toBeVisible();
+});
+```
+
+---
+
+## Debugging Tips
+
+### Interactive Mode
+
+```bash
+npx playwright test --ui
+```
+Opens a browser-based UI for running and debugging tests interactively.
+
+### Headed Mode
+
+```bash
+npx playwright test --headed
+```
+Runs tests in a visible browser window.
+
+### Trace Viewer
+
+When a test fails with `trace: 'on-first-retry'` configured:
+```bash
+npx playwright show-trace test-results/<test-folder>/trace.zip
+```
+
+### Specific Test Execution
+
+```bash
+npx playwright test e2e/auth.spec.ts                    # specific file
+npx playwright test -g "submits the login form"          # specific test by name
+npx playwright test e2e/auth.spec.ts:15                  # specific line
+```
+
+---
+
+## Things to Avoid
+
+1. **Never use `page.waitForTimeout()`**. It is a hardcoded delay that introduces flakiness. Use auto-waiting assertions or event-based waits.
+
+2. **Never use CSS class selectors** (`.btn-primary`, `.card`). Classes change during refactors and are not stable test anchors.
+
+3. **Never use XPath selectors**. They are fragile and hard to maintain. Use `data-testid` attributes.
+
+4. **Never test implementation details**. Do not assert on Redux store state, internal component state, or private API responses. Test what the user sees.
+
+5. **Never rely on test execution order**. Each test must be independently runnable. Use `test.beforeEach` for setup.
+
+6. **Never hardcode wait times**. If you find yourself adding `waitForTimeout(2000)`, there is a better way to wait (usually an assertion or `waitForResponse`).
+
+7. **Never commit `e2e-results/` or `test-results/`**. These are ephemeral outputs. They belong in `.gitignore`.