checking-wsh-vrt

name	checking-wsh-vrt
description	Runs Visual Regression Testing (VRT) locally to prevent disqualification in Web Speed Hackathon. Captures screenshots, compares against baselines, updates snapshots, and validates visual integrity after performance optimizations. Use when optimizing WSH apps, running VRT checks, updating VRT baselines, or investigating VRT failures.

Checking WSH VRT

Prevents disqualification in Web Speed Hackathon by running Visual Regression Testing locally. VRT failures mean your optimizations broke the visual appearance — and that means disqualification, no matter how fast your app is.

Use this skill when you need to run VRT checks during WSH optimization, investigate VRT failures, or update baselines after intentional visual changes.

Supporting files:

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

Project-Specific Setup

This project uses Playwright VRT with the following configuration (application/e2e/playwright.config.ts):

• Threshold: maxDiffPixelRatio: 0.03 (3% pixel diff tolerance)
• Device: Desktop Chrome (1920x1080, deviceScaleFactor: 1)
• Project name: Desktop Chrome (NOT vrt)
• Test pattern: **/src/**/*.test.ts
• Timeouts: test 300s, action 30s, navigation 30s
• Retries: 1
• Workers: CPU count / 2 (adjustable via E2E_WORKERS env var)
• Base URL: http://wsh.localhost:1355 via portless (adjustable via E2E_BASE_URL env var, default fallback: http://localhost:3000)
• Global setup: POST /api/v1/initialize is called before all tests (DB reset)

Test Files (9 test suites)

Test File	Snapshots	What it tests
home.test.ts	2	Timeline layout, 404 page
post-detail.test.ts	4	Post detail, video playing, audio, photo cover
user-profile.test.ts	1	User profile with infinite scroll, color extraction
search.test.ts	2	Search page, search results
dm.test.ts	3	DM list, new DM modal (error/success), DM detail
posting.test.ts	1	Posting modal after text input
responsive.test.ts	2	Mobile and desktop responsive views
crok-chat.test.ts	2	Crok page, after suggestions, after AI response
terms.test.ts	1	Terms of service page

Test Utilities (application/e2e/src/utils.ts)

Available helper functions used in tests:

• login(page, username, password) — Sign in flow
• waitForVisibleMedia(page) — Wait for viewport media (img/video/audio) to load
• dynamicMediaMask(page) — Mask canvas/video/GIF elements for stable screenshots
• waitForAllImagesToLoad(locator) — Wait for all images under a locator
• scrollEntire(page) — Full page scroll (up and down) to trigger lazy loads
• waitForImageToLoad(locator) — Single image naturalWidth > 0 check

Quick Start

# 1. Install Playwright browsers (first time only)
cd application/e2e && pnpm exec playwright install --with-deps chromium

# 2. Start the portless proxy (first time only)
portless proxy start 2>/dev/null || true

# 3. Build and start the app via portless
cd application && pnpm run build && portless wsh pnpm run start &

# 4. Run all VRT tests
cd application/e2e && E2E_BASE_URL=http://wsh.localhost:1355 pnpm exec playwright test

# 5. Run a single test file
cd application/e2e && E2E_BASE_URL=http://wsh.localhost:1355 pnpm exec playwright test src/home.test.ts

# 6. If tests fail, review diffs
cd application/e2e && pnpm exec playwright show-report

Core Workflow

Before Any Optimization

1. Verify VRT passes on unmodified code — If baseline is broken, fix it first
2. Commit the clean state — You need a known-good point to revert to

After Every 2-3 Optimizations

Run the full VRT check cycle:

# Start portless proxy if not running
portless proxy start 2>/dev/null || true

# Build and start via portless (ensure latest changes are reflected)
cd application && pnpm run build && portless wsh pnpm run start &

# Wait for server to be ready, then run VRT
timeout 60 bash -c 'until curl -s http://wsh.localhost:1355 > /dev/null 2>&1; do sleep 1; done'
cd application/e2e && E2E_BASE_URL=http://wsh.localhost:1355 pnpm exec playwright test

If VRT passes: Commit immediately. This is your new safe checkpoint.

If VRT fails: See the failure resolution workflow below.

VRT Failure Resolution

1. Open the HTML report to see visual diffs:

   cd application/e2e && pnpm exec 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:

   # 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):

   # Update baseline snapshots
   cd application/e2e && E2E_BASE_URL=http://wsh.localhost:1355 pnpm exec playwright test --update-snapshots
   
   # Verify the new baselines look correct
   cd application/e2e && pnpm exec 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
• Commit after every green VRT run — Your commit history is your safety net

WSH-Specific VRT Pitfalls

Optimization	VRT Risk	Mitigation
Image format conversion (AVIF/WebP)	Color shift, quality loss	Compare carefully, adjust quality parameter
Font subsetting	Missing glyphs	Verify all characters used on scored pages
CSS-in-JS removal	Style differences	Pixel-level comparison in report
Lazy loading images	Images not loaded in screenshot	Tests use waitForVisibleMedia and scrollEntire utilities
CLS fixes (dimensions)	Layout shift (intentional)	Update baselines after confirming improvement
SSR implementation	Hydration mismatch visible	Check for flicker or unstyled content
Library replacement	Rendering differences	Carefully compare component output

Running VRT with Scoring Tool

After VRT passes, confirm score impact using the in-repo scoring tool:

# Run scoring on specific target
cd scoring-tool && pnpm start http://wsh.localhost:1355 --targetName "ホームを開く"

# Run all scoring targets
cd scoring-tool && pnpm start http://wsh.localhost:1355