Checking WSH VRT

• VRT-TROUBLESHOOTING.md — Common VRT failures and fixes

Quick Start

# 1. Install dependencies (first time only)
npx playwright install --with-deps chromium

# 2. Start the app
npm run build && npm run start &

# 3. Run VRT
npx playwright test --project=vrt

# 4. If tests fail, review diffs
npx playwright show-report

Core Workflow

Before Any Optimization

1. Read

   docs/regulation.md

   — Understand what visual elements must be preserved
2. Verify VRT passes on unmodified code — If baseline is broken, fix it first
3. Commit the clean state — You need a known-good point to revert to

After Every 2-3 Optimizations

# Build and start (ensure latest changes are reflected)
npm run build && npm run start &

# Wait for server to be ready, then run VRT
npx playwright test --project=vrt

VRT Failure Resolution

1. Open the HTML report to see visual diffs:
   bash

   npx playwright show-report

2. Classify the failure:
   • Unintentional breakage — Your optimization broke something. Revert or fix.
   • Intentional change — Layout improved (e.g., CLS fix added explicit dimensions). Update baseline.
   • Flaky test — Animation timing, lazy-load race condition. Needs stabilization.
3. For unintentional breakage:
   bash

   # Revert to last known-good commit
   git stash   # or git checkout -- .

   Then re-apply optimizations one by one to isolate the culprit.
4. For intentional changes (only if regulation allows):
   bash

   # Update baseline snapshots
   npx playwright test --project=vrt --update-snapshots
   
   # Verify the new baselines look correct
   npx playwright show-report
   
   # Commit updated baselines
   git add -A '*.png'
   git commit -m "update VRT baselines: <reason>"

5. For flaky tests: See VRT-TROUBLESHOOTING.md

Critical Rules

• Never skip VRT — "I'll check later" leads to compounding visual regressions that are impossible to debug
• Never batch more than 3 changes before running VRT — Bisecting visual bugs across many changes wastes hours
• Never blindly update baselines — Every

  --update-snapshots

  must be reviewed. Blindly updating hides regulation violations
• Always read the regulation first — Some competitions have specific VRT configurations or custom comparison thresholds
• Commit after every green VRT run — Your commit history is your safety net

Regulation Awareness

• Which pages are tested — VRT may only cover scored pages
• Comparison thresholds — Pixel diff tolerance (e.g., 0.1% threshold)
• Required viewport sizes — Desktop and/or mobile
• Animation handling — Whether animations must be disabled during capture

docs/regulation.md

playwright.config.ts

WSH-Specific VRT Pitfalls

Playwright Config Check

// Expected in playwright.config.ts
{
  project: {
    name: 'vrt',
    testMatch: /.*\.vrt\.ts/,  // or similar pattern
    use: {
      // Consistent viewport for reproducible screenshots
      viewport: { width: 1440, height: 900 },
      // Animations disabled for deterministic captures
      // Check regulation for required settings
    }
  }
}

docs/regulation.md