qa-workflow-cc 1.0.0

package/skills/qa/templates/e2e-test.md

@@ -0,0 +1,1200 @@
+---
+name: e2e-test
+description: Create Playwright end-to-end tests for user flows. Use when testing complete user journeys across the application.
+context: fork
+agent: test-qa
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Write
+  - Edit
+  - Bash
+---
+
+# E2E Test Creation ({{e2eFramework}})
+
+This skill guides creation of end-to-end tests using {{e2eFramework}}.
+
+## Template Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `{{e2eFramework}}` | E2E framework (playwright, cypress) | playwright |
+| `{{baseUrl}}` | Base URL for the application | http://localhost:3000 |
+| `{{authType}}` | Auth mechanism (cookie, token, session, oauth) | cookie |
+| `{{e2eCommand}}` | Command to run E2E tests | pnpm e2e |
+| `{{e2eDir}}` | Directory for E2E test files | e2e/ |
+| `{{apiBaseUrl}}` | API base URL for mocking | /api |
+
+---
+
+## Prerequisites
+
+- Understand the user flow being tested
+- Know the expected UI states at each step
+- Have test data/fixtures ready
+- Dev server is running (or configured in playwright.config)
+
+---
+
+## Test File Structure
+
+```typescript
+// {{e2eDir}}/item-management.spec.ts
+import { test, expect } from '@playwright/test'
+
+test.describe('Item Management', () => {
+  test.beforeEach(async ({ page }) => {
+    // Authenticate before each test
+    await page.goto('/sign-in')
+    await page.fill('[data-testid="email"]', 'test@example.com')
+    await page.fill('[data-testid="password"]', 'password123')
+    await page.click('[data-testid="sign-in-button"]')
+    await page.waitForURL('/dashboard')
+  })
+
+  test('can create a new item', async ({ page }) => {
+    // Navigate
+    await page.click('[data-testid="nav-items"]')
+    await expect(page).toHaveURL('/dashboard/items')
+
+    // Open create form/modal
+    await page.click('[data-testid="create-item-button"]')
+    await expect(page.locator('[data-testid="item-modal"]')).toBeVisible()
+
+    // Fill form
+    await page.fill('[data-testid="item-name"]', 'New Item')
+    await page.fill('[data-testid="item-email"]', 'item@example.com')
+    await page.fill('[data-testid="item-phone"]', '555-123-4567')
+
+    // Submit
+    await page.click('[data-testid="submit-item"]')
+
+    // Verify success
+    await expect(page.locator('[data-testid="toast-success"]')).toBeVisible()
+    await expect(page.locator('text=New Item')).toBeVisible()
+  })
+
+  test('can edit an existing item', async ({ page }) => {
+    await page.goto('/dashboard/items')
+
+    // Click edit on first item
+    await page.locator('[data-testid="item-card"]').first()
+      .locator('[data-testid="edit-button"]').click()
+
+    // Update name
+    await page.fill('[data-testid="item-name"]', 'Updated Name')
+    await page.click('[data-testid="submit-item"]')
+
+    // Verify update
+    await expect(page.locator('text=Updated Name')).toBeVisible()
+  })
+
+  test('can delete an item with confirmation', async ({ page }) => {
+    await page.goto('/dashboard/items')
+
+    const itemCount = await page.locator('[data-testid="item-card"]').count()
+
+    // Click delete
+    await page.locator('[data-testid="item-card"]').first()
+      .locator('[data-testid="delete-button"]').click()
+
+    // Confirm deletion
+    await expect(page.locator('[data-testid="confirm-dialog"]')).toBeVisible()
+    await page.click('[data-testid="confirm-delete"]')
+
+    // Verify removal
+    await expect(page.locator('[data-testid="item-card"]')).toHaveCount(itemCount - 1)
+  })
+
+  test('can filter items by status', async ({ page }) => {
+    await page.goto('/dashboard/items')
+
+    // Select status filter
+    await page.click('[data-testid="status-filter"]')
+    await page.click('[data-testid="status-option-active"]')
+
+    // Verify filtered results
+    const badges = page.locator('[data-testid="status-badge"]')
+    const count = await badges.count()
+    for (let i = 0; i < count; i++) {
+      await expect(badges.nth(i)).toContainText('ACTIVE')
+    }
+  })
+
+  test('can search items', async ({ page }) => {
+    await page.goto('/dashboard/items')
+
+    await page.fill('[data-testid="search-input"]', 'specific item')
+    await page.waitForResponse(resp =>
+      resp.url().includes('{{apiBaseUrl}}') && resp.status() === 200
+    )
+
+    const items = page.locator('[data-testid="item-card"]')
+    const count = await items.count()
+    expect(count).toBeGreaterThan(0)
+  })
+})
+```
+
+---
+
+## Page Object Pattern
+
+For complex pages, encapsulate selectors and actions in Page Objects:
+
+```typescript
+// {{e2eDir}}/pages/ItemsPage.ts
+import { Page, Locator, expect } from '@playwright/test'
+
+export class ItemsPage {
+  readonly page: Page
+  readonly createButton: Locator
+  readonly itemCards: Locator
+  readonly searchInput: Locator
+  readonly statusFilter: Locator
+  readonly modal: Locator
+
+  constructor(page: Page) {
+    this.page = page
+    this.createButton = page.locator('[data-testid="create-item-button"]')
+    this.itemCards = page.locator('[data-testid="item-card"]')
+    this.searchInput = page.locator('[data-testid="search-input"]')
+    this.statusFilter = page.locator('[data-testid="status-filter"]')
+    this.modal = page.locator('[data-testid="item-modal"]')
+  }
+
+  async goto() {
+    await this.page.goto('/dashboard/items')
+    await expect(this.page).toHaveURL('/dashboard/items')
+  }
+
+  async createItem(data: { name: string; email: string; phone?: string }) {
+    await this.createButton.click()
+    await expect(this.modal).toBeVisible()
+
+    await this.page.fill('[data-testid="item-name"]', data.name)
+    await this.page.fill('[data-testid="item-email"]', data.email)
+    if (data.phone) {
+      await this.page.fill('[data-testid="item-phone"]', data.phone)
+    }
+    await this.page.click('[data-testid="submit-item"]')
+  }
+
+  async search(query: string) {
+    await this.searchInput.fill(query)
+    // Wait for search results to load
+    await this.page.waitForResponse(resp =>
+      resp.url().includes('{{apiBaseUrl}}') && resp.status() === 200
+    )
+  }
+
+  async filterByStatus(status: string) {
+    await this.statusFilter.click()
+    await this.page.click(`[data-testid="status-option-${status.toLowerCase()}"]`)
+  }
+
+  async getItemCount(): Promise<number> {
+    return this.itemCards.count()
+  }
+
+  async getItemByName(name: string): Promise<Locator> {
+    return this.page.locator(`[data-testid="item-card"]:has-text("${name}")`)
+  }
+
+  async editItem(name: string, updates: Record<string, string>) {
+    const card = await this.getItemByName(name)
+    await card.locator('[data-testid="edit-button"]').click()
+
+    for (const [field, value] of Object.entries(updates)) {
+      await this.page.fill(`[data-testid="item-${field}"]`, value)
+    }
+    await this.page.click('[data-testid="submit-item"]')
+  }
+
+  async deleteItem(name: string) {
+    const card = await this.getItemByName(name)
+    await card.locator('[data-testid="delete-button"]').click()
+    await this.page.click('[data-testid="confirm-delete"]')
+  }
+}
+
+// Usage in test
+import { ItemsPage } from './pages/ItemsPage'
+
+test('can create and search for an item', async ({ page }) => {
+  const itemsPage = new ItemsPage(page)
+  await itemsPage.goto()
+
+  await itemsPage.createItem({
+    name: 'Test Item',
+    email: 'test@example.com',
+  })
+
+  await itemsPage.search('Test Item')
+
+  expect(await itemsPage.getItemCount()).toBeGreaterThan(0)
+})
+```
+
+### Composing Page Objects
+
+```typescript
+// {{e2eDir}}/pages/DashboardPage.ts
+import { Page, Locator } from '@playwright/test'
+import { NavigationComponent } from './components/NavigationComponent'
+
+export class DashboardPage {
+  readonly page: Page
+  readonly nav: NavigationComponent
+  readonly statsCards: Locator
+  readonly recentActivity: Locator
+
+  constructor(page: Page) {
+    this.page = page
+    this.nav = new NavigationComponent(page)
+    this.statsCards = page.locator('[data-testid="stats-card"]')
+    this.recentActivity = page.locator('[data-testid="recent-activity"]')
+  }
+
+  async goto() {
+    await this.page.goto('/dashboard')
+  }
+
+  async getStatValue(label: string): Promise<string> {
+    const card = this.page.locator(`[data-testid="stats-card"]:has-text("${label}")`)
+    return card.locator('[data-testid="stat-value"]').textContent() ?? ''
+  }
+}
+
+// {{e2eDir}}/pages/components/NavigationComponent.ts
+export class NavigationComponent {
+  readonly page: Page
+
+  constructor(page: Page) {
+    this.page = page
+  }
+
+  async navigateTo(section: string) {
+    await this.page.click(`[data-testid="nav-${section}"]`)
+  }
+
+  async getCurrentSection(): Promise<string> {
+    const active = this.page.locator('[data-testid^="nav-"].active')
+    return active.getAttribute('data-testid') ?? ''
+  }
+}
+```
+
+---
+
+## Authentication Fixture
+
+Create reusable auth fixtures to avoid repeating login logic:
+
+```typescript
+// {{e2eDir}}/fixtures/auth.ts
+import { test as base, Page } from '@playwright/test'
+
+type AuthFixtures = {
+  authenticatedPage: Page
+  adminPage: Page
+}
+
+export const test = base.extend<AuthFixtures>({
+  authenticatedPage: async ({ page }, use) => {
+    // Login as regular user
+    await page.goto('/sign-in')
+    await page.fill('[data-testid="email"]', process.env.TEST_USER_EMAIL!)
+    await page.fill('[data-testid="password"]', process.env.TEST_USER_PASSWORD!)
+    await page.click('[data-testid="sign-in-button"]')
+    await page.waitForURL('/dashboard')
+
+    await use(page)
+
+    // Cleanup
+    await page.goto('/sign-out')
+  },
+
+  adminPage: async ({ page }, use) => {
+    // Login as admin
+    await page.goto('/sign-in')
+    await page.fill('[data-testid="email"]', process.env.TEST_ADMIN_EMAIL!)
+    await page.fill('[data-testid="password"]', process.env.TEST_ADMIN_PASSWORD!)
+    await page.click('[data-testid="sign-in-button"]')
+    await page.waitForURL('/admin/dashboard')
+
+    await use(page)
+
+    await page.goto('/sign-out')
+  },
+})
+
+export { expect } from '@playwright/test'
+
+// Usage
+import { test, expect } from './fixtures/auth'
+
+test('authenticated user can view dashboard', async ({ authenticatedPage }) => {
+  await authenticatedPage.goto('/dashboard')
+  await expect(authenticatedPage.locator('h1')).toContainText('Dashboard')
+})
+
+test('admin can access admin panel', async ({ adminPage }) => {
+  await adminPage.goto('/admin')
+  await expect(adminPage.locator('h1')).toContainText('Admin')
+})
+```
+
+### Token-Based Auth Fixture
+
+```typescript
+// {{e2eDir}}/fixtures/token-auth.ts
+import { test as base, Page } from '@playwright/test'
+
+export const test = base.extend<{ authenticatedPage: Page }>({
+  authenticatedPage: async ({ page }, use) => {
+    // Set auth token directly (faster than UI login)
+    await page.addInitScript((token) => {
+      window.localStorage.setItem('auth-token', token)
+    }, process.env.TEST_AUTH_TOKEN!)
+
+    await page.goto('/')
+    await page.waitForSelector('[data-testid="authenticated-layout"]')
+
+    await use(page)
+  },
+})
+```
+
+### Cookie-Based Auth Fixture
+
+```typescript
+// {{e2eDir}}/fixtures/cookie-auth.ts
+import { test as base, Page } from '@playwright/test'
+
+export const test = base.extend<{ authenticatedPage: Page }>({
+  authenticatedPage: async ({ page, context }, use) => {
+    // Set auth cookie directly
+    await context.addCookies([{
+      name: 'session',
+      value: process.env.TEST_SESSION_TOKEN!,
+      domain: 'localhost',
+      path: '/',
+    }])
+
+    await page.goto('/')
+    await page.waitForSelector('[data-testid="authenticated-layout"]')
+
+    await use(page)
+  },
+})
+```
+
+### Saved Auth State (Persistent Login)
+
+```typescript
+// {{e2eDir}}/auth.setup.ts
+import { test as setup, expect } from '@playwright/test'
+import path from 'path'
+
+const authFile = path.join(__dirname, '.auth/user.json')
+
+setup('authenticate', async ({ page }) => {
+  await page.goto('/sign-in')
+  await page.fill('[data-testid="email"]', process.env.TEST_USER_EMAIL!)
+  await page.fill('[data-testid="password"]', process.env.TEST_USER_PASSWORD!)
+  await page.click('[data-testid="sign-in-button"]')
+  await page.waitForURL('/dashboard')
+
+  // Save signed-in state
+  await page.context().storageState({ path: authFile })
+})
+
+// In playwright.config.ts:
+// projects: [
+//   { name: 'setup', testMatch: /.*\.setup\.ts/ },
+//   { name: 'tests', dependencies: ['setup'], use: { storageState: authFile } },
+// ]
+```
+
+---
+
+## Visual Testing
+
+```typescript
+test.describe('Visual Regression', () => {
+  test('dashboard matches snapshot', async ({ page }) => {
+    await page.goto('/dashboard')
+    await page.waitForLoadState('networkidle')
+
+    // Full page screenshot
+    await expect(page).toHaveScreenshot('dashboard.png', {
+      fullPage: true,
+      maxDiffPixels: 100,
+    })
+  })
+
+  test('item card matches snapshot', async ({ page }) => {
+    await page.goto('/dashboard/items')
+
+    // Component screenshot
+    const card = page.locator('[data-testid="item-card"]').first()
+    await expect(card).toHaveScreenshot('item-card.png')
+  })
+
+  test('dark mode matches snapshot', async ({ page }) => {
+    await page.emulateMedia({ colorScheme: 'dark' })
+    await page.goto('/dashboard')
+    await page.waitForLoadState('networkidle')
+
+    await expect(page).toHaveScreenshot('dashboard-dark.png', {
+      fullPage: true,
+    })
+  })
+
+  test('responsive layout matches snapshot', async ({ page }) => {
+    // Test at different viewport sizes
+    const viewports = [
+      { width: 375, height: 812, name: 'mobile' },
+      { width: 768, height: 1024, name: 'tablet' },
+      { width: 1440, height: 900, name: 'desktop' },
+    ]
+
+    for (const vp of viewports) {
+      await page.setViewportSize({ width: vp.width, height: vp.height })
+      await page.goto('/dashboard')
+      await page.waitForLoadState('networkidle')
+
+      await expect(page).toHaveScreenshot(`dashboard-${vp.name}.png`, {
+        maxDiffPixels: 50,
+      })
+    }
+  })
+})
+```
+
+---
+
+## API Mocking
+
+Intercept API calls to test specific states without backend dependencies:
+
+```typescript
+test.describe('Error Handling', () => {
+  test('handles API error gracefully', async ({ page }) => {
+    // Mock API to return error
+    await page.route('**/{{apiBaseUrl}}/items*', (route) => {
+      route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({ error: 'Internal Server Error' }),
+      })
+    })
+
+    await page.goto('/dashboard/items')
+
+    // Verify error state
+    await expect(page.locator('[data-testid="error-message"]')).toBeVisible()
+    await expect(page.locator('[data-testid="retry-button"]')).toBeVisible()
+  })
+
+  test('shows loading state', async ({ page }) => {
+    // Delay API response
+    await page.route('**/{{apiBaseUrl}}/items*', async (route) => {
+      await new Promise(resolve => setTimeout(resolve, 2000))
+      route.continue()
+    })
+
+    await page.goto('/dashboard/items')
+
+    // Verify loading state
+    await expect(page.locator('[data-testid="loading-skeleton"]')).toBeVisible()
+  })
+
+  test('handles empty response', async ({ page }) => {
+    await page.route('**/{{apiBaseUrl}}/items*', (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({ items: [], total: 0 }),
+      })
+    })
+
+    await page.goto('/dashboard/items')
+
+    await expect(page.locator('[data-testid="empty-state"]')).toBeVisible()
+    await expect(page.locator('text=No items yet')).toBeVisible()
+  })
+
+  test('handles network timeout', async ({ page }) => {
+    await page.route('**/{{apiBaseUrl}}/items*', (route) => {
+      route.abort('timedout')
+    })
+
+    await page.goto('/dashboard/items')
+
+    await expect(page.locator('[data-testid="error-message"]')).toBeVisible()
+  })
+})
+```
+
+### Intercepting and Modifying Responses
+
+```typescript
+test('shows notification badge for new messages', async ({ page }) => {
+  await page.route('**/{{apiBaseUrl}}/notifications/count*', (route) => {
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ unreadCount: 5 }),
+    })
+  })
+
+  await page.goto('/dashboard')
+
+  const badge = page.locator('[data-testid="notification-badge"]')
+  await expect(badge).toBeVisible()
+  await expect(badge).toContainText('5')
+})
+```
+
+---
+
+## Mobile Testing
+
+```typescript
+import { devices } from '@playwright/test'
+
+test.describe('Mobile', () => {
+  test.use({ ...devices['iPhone 13'] })
+
+  test('navigation menu opens on mobile', async ({ page }) => {
+    await page.goto('/dashboard')
+
+    // Mobile menu should be hidden initially
+    await expect(page.locator('[data-testid="mobile-menu"]')).toBeHidden()
+
+    // Click hamburger
+    await page.click('[data-testid="hamburger-button"]')
+
+    // Menu should be visible
+    await expect(page.locator('[data-testid="mobile-menu"]')).toBeVisible()
+  })
+
+  test('can navigate via mobile menu', async ({ page }) => {
+    await page.goto('/dashboard')
+
+    await page.click('[data-testid="hamburger-button"]')
+    await page.click('[data-testid="mobile-nav-items"]')
+
+    await expect(page).toHaveURL('/dashboard/items')
+  })
+
+  test('forms are usable on mobile', async ({ page }) => {
+    await page.goto('/dashboard/items/new')
+
+    // Verify form fields are tappable (large enough touch targets)
+    const nameInput = page.locator('[data-testid="item-name"]')
+    const box = await nameInput.boundingBox()
+
+    expect(box).toBeTruthy()
+    expect(box!.height).toBeGreaterThanOrEqual(44) // Min touch target
+
+    // Fill and submit form
+    await nameInput.fill('Mobile Item')
+    await page.fill('[data-testid="item-email"]', 'mobile@example.com')
+    await page.click('[data-testid="submit-item"]')
+
+    await expect(page.locator('[data-testid="toast-success"]')).toBeVisible()
+  })
+
+  test('cards stack vertically on mobile', async ({ page }) => {
+    await page.goto('/dashboard/items')
+
+    const cards = page.locator('[data-testid="item-card"]')
+    const count = await cards.count()
+
+    if (count >= 2) {
+      const first = await cards.nth(0).boundingBox()
+      const second = await cards.nth(1).boundingBox()
+
+      expect(first).toBeTruthy()
+      expect(second).toBeTruthy()
+      // Second card should be below the first (stacked vertically)
+      expect(second!.y).toBeGreaterThan(first!.y)
+      // Both should have similar x position (same column)
+      expect(Math.abs(first!.x - second!.x)).toBeLessThan(10)
+    }
+  })
+})
+
+test.describe('Tablet', () => {
+  test.use({ ...devices['iPad Pro 11'] })
+
+  test('shows sidebar navigation on tablet', async ({ page }) => {
+    await page.goto('/dashboard')
+
+    await expect(page.locator('[data-testid="sidebar"]')).toBeVisible()
+    await expect(page.locator('[data-testid="hamburger-button"]')).toBeHidden()
+  })
+})
+```
+
+---
+
+## Test Data Management
+
+### Using Fixtures
+
+```typescript
+// {{e2eDir}}/fixtures/testData.ts
+export const testItems = [
+  {
+    name: 'Test Item Alpha',
+    email: 'alpha@test.com',
+    phone: '555-111-1111',
+    status: 'ACTIVE',
+  },
+  {
+    name: 'Test Item Beta',
+    email: 'beta@test.com',
+    phone: '555-222-2222',
+    status: 'INACTIVE',
+  },
+  {
+    name: 'Test Item Gamma',
+    email: 'gamma@test.com',
+    phone: '555-333-3333',
+    status: 'PENDING',
+  },
+]
+
+export const testUsers = {
+  regular: {
+    email: 'testuser@example.com',
+    password: 'TestPass123!',
+    name: 'Test User',
+  },
+  admin: {
+    email: 'admin@example.com',
+    password: 'AdminPass123!',
+    name: 'Admin User',
+  },
+}
+```
+
+### Seeding and Cleaning Up
+
+```typescript
+// Seed data before tests
+test.beforeAll(async ({ request }) => {
+  await request.post('{{baseUrl}}/api/test/seed', {
+    data: { items: testItems },
+  })
+})
+
+// Clean up after tests
+test.afterAll(async ({ request }) => {
+  await request.post('{{baseUrl}}/api/test/cleanup')
+})
+```
+
+### Database Seed Script Pattern
+
+```typescript
+// {{e2eDir}}/fixtures/seed.ts
+import { test as setup } from '@playwright/test'
+
+setup('seed test data', async ({ request }) => {
+  // Create test organization
+  const orgResponse = await request.post('{{baseUrl}}/api/test/setup', {
+    data: {
+      orgName: 'Test Organization',
+      users: [
+        { email: 'user@test.com', role: 'member' },
+        { email: 'admin@test.com', role: 'admin' },
+      ],
+    },
+  })
+
+  expect(orgResponse.ok()).toBeTruthy()
+
+  // Create test data within that org
+  await request.post('{{baseUrl}}/api/test/seed', {
+    data: { items: testItems },
+    headers: {
+      'x-test-org': (await orgResponse.json()).orgId,
+    },
+  })
+})
+```
+
+---
+
+## Waiting Strategies
+
+| Strategy | Use When |
+|----------|----------|
+| `waitForURL(url)` | After navigation (click a link, submit form) |
+| `waitForResponse(url)` | After API call triggered by user action |
+| `waitForLoadState('networkidle')` | Page fully loaded, no pending requests |
+| `waitForSelector(selector)` | Specific element appears in DOM |
+| `expect(locator).toBeVisible()` | Element is visible (auto-waits) |
+| `waitForTimeout(ms)` | Last resort only (avoid in production tests) |
+
+```typescript
+// Wait for navigation
+await page.click('[data-testid="nav-items"]')
+await page.waitForURL('/dashboard/items')
+
+// Wait for specific API response
+await page.fill('[data-testid="search"]', 'query')
+await page.waitForResponse(resp =>
+  resp.url().includes('{{apiBaseUrl}}/search') && resp.status() === 200
+)
+
+// Wait for network to be idle
+await page.goto('/dashboard')
+await page.waitForLoadState('networkidle')
+
+// Wait for element to appear
+await expect(page.locator('[data-testid="results"]')).toBeVisible()
+
+// Wait for element to disappear
+await expect(page.locator('[data-testid="spinner"]')).toBeHidden()
+
+// Wait for element text content
+await expect(page.locator('[data-testid="count"]')).toContainText('42')
+
+// Combine with timeout for slow operations
+await expect(page.locator('[data-testid="report"]')).toBeVisible({
+  timeout: 30_000, // 30s for slow report generation
+})
+```
+
+### Anti-Patterns
+
+```typescript
+// BAD - Fixed timeout (flaky!)
+await page.waitForTimeout(3000)
+
+// GOOD - Wait for specific condition
+await page.waitForResponse('**/api/data')
+
+// BAD - Polling with sleep
+while (!(await page.isVisible('.loaded'))) {
+  await page.waitForTimeout(100)
+}
+
+// GOOD - Built-in auto-waiting
+await expect(page.locator('.loaded')).toBeVisible()
+```
+
+---
+
+## Multi-Tab / Multi-User Testing
+
+Test real-time features or multi-role workflows:
+
+```typescript
+test('real-time updates between two users', async ({ browser }) => {
+  // Open first browser context (User A)
+  const contextA = await browser.newContext()
+  const pageA = await contextA.newPage()
+  // ... authenticate as User A
+
+  // Open second browser context (User B)
+  const contextB = await browser.newContext()
+  const pageB = await contextB.newPage()
+  // ... authenticate as User B
+
+  // User A creates an item
+  await pageA.goto('/dashboard/items')
+  await pageA.click('[data-testid="create-item-button"]')
+  await pageA.fill('[data-testid="item-name"]', 'Shared Item')
+  await pageA.click('[data-testid="submit-item"]')
+
+  // User B should see the new item (real-time update)
+  await pageB.goto('/dashboard/items')
+  await expect(pageB.locator('text=Shared Item')).toBeVisible({ timeout: 10_000 })
+
+  // Cleanup
+  await contextA.close()
+  await contextB.close()
+})
+
+test('admin and regular user see different views', async ({ browser }) => {
+  const adminContext = await browser.newContext()
+  const adminPage = await adminContext.newPage()
+  // ... authenticate as admin
+
+  const userContext = await browser.newContext()
+  const userPage = await userContext.newPage()
+  // ... authenticate as regular user
+
+  // Admin sees admin panel link
+  await adminPage.goto('/dashboard')
+  await expect(adminPage.locator('[data-testid="admin-link"]')).toBeVisible()
+
+  // Regular user does not
+  await userPage.goto('/dashboard')
+  await expect(userPage.locator('[data-testid="admin-link"]')).toBeHidden()
+
+  await adminContext.close()
+  await userContext.close()
+})
+```
+
+---
+
+## Form Testing Patterns
+
+```typescript
+test.describe('Multi-Step Form', () => {
+  test('completes full form wizard', async ({ page }) => {
+    await page.goto('/onboarding')
+
+    // Step 1: Personal info
+    await page.fill('[data-testid="first-name"]', 'Jane')
+    await page.fill('[data-testid="last-name"]', 'Smith')
+    await page.click('[data-testid="next-step"]')
+
+    // Step 2: Company info
+    await expect(page.locator('[data-testid="step-indicator"]')).toContainText('2 of 3')
+    await page.fill('[data-testid="company-name"]', 'Acme Corp')
+    await page.click('[data-testid="next-step"]')
+
+    // Step 3: Review and submit
+    await expect(page.locator('[data-testid="step-indicator"]')).toContainText('3 of 3')
+    await expect(page.locator('text=Jane Smith')).toBeVisible()
+    await expect(page.locator('text=Acme Corp')).toBeVisible()
+    await page.click('[data-testid="submit-form"]')
+
+    // Success state
+    await expect(page.locator('[data-testid="success-message"]')).toBeVisible()
+  })
+
+  test('can go back and edit previous steps', async ({ page }) => {
+    await page.goto('/onboarding')
+
+    // Fill step 1
+    await page.fill('[data-testid="first-name"]', 'Jane')
+    await page.click('[data-testid="next-step"]')
+
+    // Go back
+    await page.click('[data-testid="prev-step"]')
+
+    // Verify data is preserved
+    await expect(page.locator('[data-testid="first-name"]')).toHaveValue('Jane')
+  })
+
+  test('shows validation errors on incomplete step', async ({ page }) => {
+    await page.goto('/onboarding')
+
+    // Try to advance without filling required fields
+    await page.click('[data-testid="next-step"]')
+
+    await expect(page.locator('[data-testid="error-first-name"]')).toBeVisible()
+  })
+})
+```
+
+---
+
+## File Upload Testing
+
+```typescript
+test('can upload a file', async ({ page }) => {
+  await page.goto('/dashboard/items/1')
+
+  // Trigger file upload
+  const fileInput = page.locator('input[type="file"]')
+  await fileInput.setInputFiles({
+    name: 'test-document.pdf',
+    mimeType: 'application/pdf',
+    buffer: Buffer.from('fake pdf content'),
+  })
+
+  // Verify upload success
+  await expect(page.locator('[data-testid="upload-success"]')).toBeVisible()
+  await expect(page.locator('text=test-document.pdf')).toBeVisible()
+})
+
+test('can upload multiple images', async ({ page }) => {
+  await page.goto('/dashboard/items/1/photos')
+
+  const fileInput = page.locator('input[type="file"]')
+  await fileInput.setInputFiles([
+    { name: 'photo1.jpg', mimeType: 'image/jpeg', buffer: Buffer.from('img1') },
+    { name: 'photo2.jpg', mimeType: 'image/jpeg', buffer: Buffer.from('img2') },
+  ])
+
+  await expect(page.locator('[data-testid="photo-thumbnail"]')).toHaveCount(2)
+})
+
+test('shows error for invalid file type', async ({ page }) => {
+  await page.goto('/dashboard/items/1')
+
+  const fileInput = page.locator('input[type="file"]')
+  await fileInput.setInputFiles({
+    name: 'malware.exe',
+    mimeType: 'application/octet-stream',
+    buffer: Buffer.from('bad content'),
+  })
+
+  await expect(page.locator('[data-testid="upload-error"]')).toBeVisible()
+  await expect(page.locator('text=File type not supported')).toBeVisible()
+})
+```
+
+---
+
+## Accessibility Testing in E2E
+
+```typescript
+import { test, expect } from '@playwright/test'
+import AxeBuilder from '@axe-core/playwright'
+
+test.describe('Accessibility', () => {
+  test('dashboard has no a11y violations', async ({ page }) => {
+    await page.goto('/dashboard')
+    await page.waitForLoadState('networkidle')
+
+    const results = await new AxeBuilder({ page }).analyze()
+
+    expect(results.violations).toEqual([])
+  })
+
+  test('form page has no a11y violations', async ({ page }) => {
+    await page.goto('/dashboard/items/new')
+
+    const results = await new AxeBuilder({ page })
+      .include('[data-testid="item-form"]')
+      .analyze()
+
+    expect(results.violations).toEqual([])
+  })
+
+  test('keyboard navigation works', async ({ page }) => {
+    await page.goto('/dashboard')
+
+    // Tab through navigation
+    await page.keyboard.press('Tab')
+    const firstFocused = await page.evaluate(() => document.activeElement?.tagName)
+    expect(firstFocused).toBeTruthy()
+
+    // Can activate button with Enter
+    await page.keyboard.press('Tab') // Move to a button
+    await page.keyboard.press('Enter')
+  })
+})
+```
+
+---
+
+## PWA Testing
+
+```typescript
+test.describe('PWA Features', () => {
+  test('service worker registers', async ({ page }) => {
+    await page.goto('{{baseUrl}}')
+
+    const swRegistered = await page.evaluate(async () => {
+      const registrations = await navigator.serviceWorker.getRegistrations()
+      return registrations.length > 0
+    })
+    expect(swRegistered).toBe(true)
+  })
+
+  test('manifest is valid', async ({ page }) => {
+    const response = await page.goto('{{baseUrl}}/manifest.json')
+    const manifest = await response?.json()
+
+    expect(manifest.name).toBeDefined()
+    expect(manifest.icons).toBeDefined()
+    expect(manifest.icons.length).toBeGreaterThan(0)
+    expect(manifest.start_url).toBeDefined()
+    expect(manifest.display).toBe('standalone')
+  })
+
+  test('works offline for cached pages', async ({ page, context }) => {
+    // Load page first to cache
+    await page.goto('{{baseUrl}}/dashboard')
+    await page.waitForLoadState('networkidle')
+
+    // Go offline
+    await context.setOffline(true)
+
+    // Navigate to cached page
+    await page.goto('{{baseUrl}}/dashboard')
+
+    // Should still show content
+    await expect(page.locator('h1')).toBeVisible()
+  })
+})
+```
+
+---
+
+## Playwright Config
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test'
+
+export default defineConfig({
+  testDir: './{{e2eDir}}',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html'],
+    ['json', { outputFile: 'test-results/results.json' }],
+  ],
+
+  use: {
+    baseURL: '{{baseUrl}}',
+    trace: 'on-first-retry',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+
+  projects: [
+    // Setup project for auth
+    {
+      name: 'setup',
+      testMatch: /.*\.setup\.ts/,
+    },
+    // Desktop browsers
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+      dependencies: ['setup'],
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+      dependencies: ['setup'],
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+      dependencies: ['setup'],
+    },
+    // Mobile browsers
+    {
+      name: 'Mobile Chrome',
+      use: { ...devices['Pixel 5'] },
+      dependencies: ['setup'],
+    },
+    {
+      name: 'Mobile Safari',
+      use: { ...devices['iPhone 12'] },
+      dependencies: ['setup'],
+    },
+  ],
+
+  webServer: {
+    command: 'pnpm dev',
+    url: '{{baseUrl}}',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+})
+```
+
+---
+
+## Environment Variables for E2E
+
+```bash
+# .env.test
+TEST_USER_EMAIL=testuser@example.com
+TEST_USER_PASSWORD=TestPass123!
+TEST_ADMIN_EMAIL=admin@example.com
+TEST_ADMIN_PASSWORD=AdminPass123!
+BASE_URL={{baseUrl}}
+```
+
+---
+
+## Checklist
+
+Before submitting E2E tests:
+
+- [ ] Tests cover critical user paths (happy path)
+- [ ] Error states are tested (API failures, validation errors)
+- [ ] Page Objects used for complex pages (3+ interactions)
+- [ ] Authentication handled via fixture (not repeated in each test)
+- [ ] API mocking for error/edge states
+- [ ] Mobile viewport tested for responsive layouts
+- [ ] No flaky selectors (use data-testid, not CSS classes)
+- [ ] Proper waiting strategies used (no `waitForTimeout`)
+- [ ] Test data seeded and cleaned up
+- [ ] Screenshots/traces configured for failures
+- [ ] Keyboard navigation tested for key flows
+- [ ] Multi-step flows tested end-to-end
+- [ ] File uploads tested (if applicable)
+
+---
+
+## Running E2E Tests
+
+```bash
+# Run all E2E tests
+{{e2eCommand}}
+
+# Run with UI mode (interactive debugging)
+{{e2eCommand}} --ui
+
+# Run specific test file
+{{e2eCommand}} {{e2eDir}}/item-management.spec.ts
+
+# Run in headed mode (visible browser)
+{{e2eCommand}} --headed
+
+# Run specific project (browser)
+{{e2eCommand}} --project=chromium
+
+# Run with debug mode (step through)
+PWDEBUG=1 {{e2eCommand}}
+
+# Generate HTML report
+{{e2eCommand}} --reporter=html
+
+# Update visual snapshots
+{{e2eCommand}} --update-snapshots
+
+# Run in CI mode (all browsers, retries)
+CI=true {{e2eCommand}}
+```
+
+---
+
+## Debugging Failed Tests
+
+```typescript
+// Add debug logging to failing tests
+test('debug example', async ({ page }) => {
+  // Enable verbose logging
+  page.on('console', msg => console.log('BROWSER:', msg.text()))
+  page.on('requestfailed', req => console.log('FAILED:', req.url(), req.failure()?.errorText))
+
+  // Pause execution for manual debugging
+  await page.pause() // Opens Playwright Inspector
+
+  // Take screenshot at specific point
+  await page.screenshot({ path: 'debug-screenshot.png', fullPage: true })
+})
+```
+
+---
+
+## See Also
+
+- `unit-test.md` - Unit testing patterns
+- `component-test.md` - Component testing patterns
+- `test-standards.md` - Coverage thresholds and test type requirements