Test need → Is it a pure unit (function/hook)?
    ├─ Yes → Jest in packages/
    └─ No → Playwright E2E

Playwright task → Is the dev server running?
    ├─ No  → Use with_server.py helper OR next dev directly
    └─ Yes → Reconnaissance-then-action pattern

# From monorepo root
pnpm --filter web dev # starts on :3000

# Or in test scripts — use playwright's webServer config

import { defineConfig, devices } from '@playwright/test'

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [['html', { outputFolder: 'playwright-report' }]],
  
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },

  // Auto-start dev server for local testing
  webServer: {
    command: 'pnpm --filter web dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
    timeout: 120000,
  },

  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'Mobile Safari', use: { ...devices['iPhone 14'] } },
  ],
})

import { test, expect } from '@playwright/test'

test('lore page loads', async ({ page }) => {
  // 1. Navigate and wait
  await page.goto('/lore')
  await page.waitForLoadState('networkidle') // CRITICAL for Next.js hydration

  // 2. Reconnaissance — take screenshot to understand DOM state
  await page.screenshot({ path: 'tests/screenshots/lore-debug.png', fullPage: true })

  // 3. Identify selectors from rendered state
  const guardianCards = page.locator('[data-testid="guardian-card"]')
  const count = await guardianCards.count()
  console.log(`Found ${count} guardian cards`)

  // 4. Assert
  expect(count).toBeGreaterThanOrEqual(1)
})

test('gate quiz — foundation gate completion', async ({ page }) => {
  // Auth: sign in as test user
  await page.goto('/auth/sign-in')
  await page.waitForLoadState('networkidle')
  await page.fill('[data-testid="email-input"]', process.env.TEST_USER_EMAIL!)
  await page.fill('[data-testid="password-input"]', process.env.TEST_USER_PASSWORD!)
  await page.click('[data-testid="sign-in-btn"]')
  await page.waitForURL('/academy')

  // Navigate to Foundation Gate quiz
  await page.goto('/academy/gate-quiz?gate=foundation')
  await page.waitForLoadState('networkidle')

  // Answer questions (10 questions for Foundation gate)
  for (let i = 0; i < 10; i++) {
    const question = page.locator('[data-testid="quiz-question"]')
    await expect(question).toBeVisible()
    
    // Select first answer (test data has correct first answers)
    await page.locator('[data-testid="answer-option"]').first().click()
    await page.locator('[data-testid="next-question-btn"]').click()
  }

  // Verify completion screen
  await expect(page.locator('[data-testid="gate-complete"]')).toBeVisible()
  await expect(page.locator('[data-testid="guardian-name"]')).toContainText('Lyssandria')
})

test('lore explore — elements navigation', async ({ page }) => {
  await page.goto('/lore')
  await page.waitForLoadState('networkidle')

  // Test all five elements navigation
  const elements = ['fire', 'water', 'earth', 'wind', 'void']
  
  for (const element of elements) {
    await page.goto(`/lore/elements/${element}`)
    await page.waitForLoadState('networkidle')
    
    // Verify element page loads with correct title
    const title = page.locator('h1, [data-testid="element-title"]')
    await expect(title).toBeVisible()
    await expect(title).toContainText(element, { ignoreCase: true })
  }
})

test('prompt books — create and view prompt', async ({ page }) => {
  await authenticateTestUser(page)
  
  await page.goto('/prompt-books')
  await page.waitForLoadState('networkidle')

  // Create new prompt
  await page.click('[data-testid="new-prompt-btn"]')
  await page.waitForLoadState('networkidle')

  // Fill editor
  await page.fill('[data-testid="prompt-title"]', 'Test Guardian Invocation')
  await page.locator('[data-testid="prompt-editor"]').click()
  await page.keyboard.type('Channel the essence of {element} through {gate}')
  
  await page.click('[data-testid="save-prompt-btn"]')
  
  // Verify saved
  await expect(page.locator('[data-testid="save-success"]')).toBeVisible()
  
  // Navigate back and verify prompt appears
  await page.goto('/prompt-books')
  await expect(page.locator('text=Test Guardian Invocation')).toBeVisible()
})

test('guardian card visual snapshot', async ({ page }) => {
  await page.goto('/lore/guardians')
  await page.waitForLoadState('networkidle')
  
  // Wait for glassmorphism animations to settle
  await page.waitForTimeout(500)
  
  // Snapshot the guardian grid
  const grid = page.locator('[data-testid="guardian-grid"]')
  await expect(grid).toHaveScreenshot('guardian-grid.png', {
    maxDiffPixelRatio: 0.02, // 2% tolerance for antialiasing
  })
})

// tests/helpers/auth.ts — reuse across tests
import { type Page } from '@playwright/test'

export async function authenticateTestUser(page: Page) {
  await page.goto('/auth/sign-in')
  await page.waitForLoadState('networkidle')
  await page.fill('[name="email"]', process.env.TEST_USER_EMAIL!)
  await page.fill('[name="password"]', process.env.TEST_USER_PASSWORD!)
  await page.click('[type="submit"]')
  await page.waitForURL(/\/(academy|dashboard|lore)/)
}

// Use storage state for faster auth across tests
// playwright.config.ts: use: { storageState: 'playwright/.auth/user.json' }

// tests/auth.setup.ts — runs before test suite
import { test as setup } from '@playwright/test'
import { authenticateTestUser } from './helpers/auth'

const authFile = 'playwright/.auth/user.json'

setup('authenticate', async ({ page }) => {
  await authenticateTestUser(page)
  await page.context().storageState({ path: authFile })
})

// Always after navigation to dynamic Next.js pages
await page.goto('/path')
await page.waitForLoadState('networkidle') // waits for all network requests

// Inline debug screenshot (delete after fixing)
await page.screenshot({ path: `/tmp/debug-${Date.now()}.png`, fullPage: true })

// In components: always add data-testid for critical interactive elements
<button data-testid="unlock-gate-btn" onClick={handleUnlock}>
  Unlock Gate
</button>

// In tests: prefer data-testid over CSS selectors (resilient to style changes)
await page.click('[data-testid="unlock-gate-btn"]')

// Mock Supabase/API calls in tests
await page.route('/api/guardians', async route => {
  await route.fulfill({
    status: 200,
    contentType: 'application/json',
    body: JSON.stringify(MOCK_GUARDIANS),
  })
})

# From apps/web directory
cd apps/web

# Run all E2E tests
npx playwright test

# Run specific test file
npx playwright test tests/e2e/lore.spec.ts

# Run with UI mode (visual debugger)
npx playwright test --ui

# Debug specific test
npx playwright test --debug tests/e2e/gate-quiz.spec.ts

# Update snapshots
npx playwright test --update-snapshots

# View report
npx playwright show-report