Back to Details

checking-wsh-vrt

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Checking WSH VRT

检查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
通过在本地运行Visual Regression Testing，避免在Web Speed Hackathon中被取消资格。VRT失败意味着你的优化破坏了视觉外观——无论你的应用速度有多快，这都会导致取消资格。
适用场景：在WSH优化期间需要执行VRT检查、排查VRT失败问题，或在有意修改视觉效果后更新基准版本时。
相关支持文件：
  • VRT-TROUBLESHOOTING.md — 常见VRT失败问题及修复方案

Quick Start

快速开始

bash
undefined
bash
undefined

1. Install dependencies (first time only)

1. Install dependencies (first time only)

npx playwright install --with-deps chromium
npx playwright install --with-deps chromium

2. Start the app

2. Start the app

npm run build && npm run start &
npm run build && npm run start &

3. Run VRT

3. Run VRT

npx playwright test --project=vrt
npx playwright test --project=vrt

4. If tests fail, review diffs

4. If tests fail, review diffs

npx playwright show-report
undefined
npx playwright show-report
undefined

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
  1. 阅读
    docs/regulation.md
     — 了解必须保留的视觉元素
  2. 验证未修改代码的VRT检查通过 — 如果基准版本存在问题，请先修复
  3. 提交干净状态的代码 — 你需要一个已知可用的版本作为回退点

After Every 2-3 Optimizations

每完成2-3项优化后

Run the full VRT check cycle:
bash
undefined
执行完整的VRT检查流程：
bash
undefined

Build and start (ensure latest changes are reflected)

Build and start (ensure latest changes are reflected)

npm run build && npm run start &
npm run build && npm run start &

Wait for server to be ready, then run VRT

Wait for server to be ready, then run VRT

npx playwright test --project=vrt

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

**If VRT fails**: See the failure resolution workflow below.
npx playwright test --project=vrt

**如果VRT检查通过**：立即提交代码。这将成为你新的安全检查点。

**如果VRT检查失败**：请遵循以下失败解决流程。

VRT Failure Resolution

VRT失败解决流程

  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
  1. 打开HTML报告查看视觉差异：
    bash
    npx playwright show-report
  2. 对失败类型进行分类：
    • 意外损坏 — 你的优化导致了问题。回退或修复。
    • 有意修改 — 布局得到改进（例如，CLS修复添加了明确的尺寸）。更新基准版本。
    • 不稳定测试 — 动画时序、懒加载竞争条件。需要稳定测试。
  3. 针对意外损坏：
    bash
    # Revert to last known-good commit
git stash   # or git checkout -- .
    然后逐个重新应用优化，以定位问题根源。
  4. 针对有意修改（仅在规则允许的情况下）：
    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. 针对不稳定测试：请查看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
  • 切勿跳过VRT检查 — "稍后再检查"会导致视觉回归问题不断累积，最终难以调试
  • 每次提交的更改不要超过3项 — 在多项更改中排查视觉bug会浪费大量时间
  • 切勿盲目更新基准版本 — 每次使用
    --update-snapshots
    都必须经过审核。盲目更新会掩盖违反规则的问题
  • 务必先阅读规则 — 部分竞赛有特定的VRT配置或自定义对比阈值
  • 每次VRT检查通过后都要提交代码 — 你的提交历史是安全保障

Regulation Awareness

规则注意事项

WSH regulations typically specify:
  • 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
Check 
docs/regulation.md
and the VRT config (usually 
playwright.config.ts
) for project-specific settings.
WSH规则通常会明确：
  • 测试页面范围 — VRT可能仅覆盖评分页面
  • 对比阈值 — 像素差异容忍度（例如0.1%的阈值）
  • 要求的视口尺寸 — 桌面端和/或移动端
  • 动画处理方式 — 捕获截图时是否必须禁用动画
请查看
docs/regulation.md
和VRT配置文件（通常为
playwright.config.ts
）获取项目特定设置。

WSH-Specific VRT Pitfalls

WSH特定VRT陷阱

OptimizationVRT RiskMitigation
Image format conversion (AVIF/WebP)Color shift, quality lossCompare carefully, adjust quality parameter
Font subsettingMissing glyphsVerify all characters used on scored pages
CSS-in-JS removalStyle differencesPixel-level comparison in report
Lazy loading imagesImages not loaded in screenshotEnsure scroll/wait in test or disable lazy for VRT
CLS fixes (dimensions)Layout shift (intentional)Update baselines after confirming improvement
SSR implementationHydration mismatch visibleCheck for flicker or unstyled content
Library replacementRendering differencesCarefully compare component output
优化操作VRT风险缓解措施
图片格式转换（AVIF/WebP）颜色偏移、画质损失仔细对比，调整画质参数
字体子集化缺失字形验证评分页面使用的所有字符
移除CSS-in-JS样式差异在报告中进行像素级对比
图片懒加载截图中未加载图片确保测试中包含滚动/等待操作，或为VRT禁用懒加载
CLS修复（设置尺寸）布局偏移（有意修改）确认改进后更新基准版本
SSR实现可见的 hydration 不匹配检查是否有闪烁或未样式化内容
库替换渲染差异仔细对比组件输出结果

Playwright Config Check

Playwright配置检查

Before running VRT, verify the Playwright config has correct VRT settings:
typescript
// 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
    }
  }
}
If the project doesn't have VRT configured, check 
docs/regulation.md
for the competition's expected VRT setup before creating your own.
运行VRT前，请验证Playwright配置是否包含正确的VRT设置：
typescript
// 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
    }
  }
}
如果项目未配置VRT，请在自行创建前查看
docs/regulation.md
获取竞赛要求的VRT设置。