agent-capabilities

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Capabilities - Visual Regression Testing

Agent能力 - 视觉回归测试

This document outlines Claude's comprehensive capabilities for implementing and managing visual regression testing infrastructure in web applications.

本文档概述了Claude在Web应用中实施和管理视觉回归测试基础设施的全面能力。

Core Competencies

核心能力

1. Visual Regression Testing Infrastructure

1. 视觉回归测试基础设施

Claude can set up complete visual regression testing infrastructure following industry best practices from Ant Design, Argos CI, and other leading organizations.

Capabilities:

✅ Configure Playwright for visual testing
✅ Implement jest-image-snapshot for pixel-perfect comparison
✅ Create baseline screenshot management system
✅ Generate visual diff reports with HTML/Markdown output
✅ Set up multi-viewport and multi-browser testing
✅ Configure threshold-based comparison with anti-aliasing detection

Implementation Reference:

Skill:

.claude/skills/visual-regression-testing/SKILL.md

Test utilities:
```
tests/shared/imageTest.tsx
```
Scripts:
```
scripts/visual-regression/
```

Claude能够遵循Ant Design、Argos CI等领先组织的行业最佳实践，搭建完整的视觉回归测试基础设施。

能力清单：

✅ 配置Playwright用于视觉测试
✅ 实施jest-image-snapshot进行像素级精准对比
✅ 创建基准截图管理系统
✅ 生成带HTML/Markdown输出的视觉差异报告
✅ 搭建多视口和多浏览器测试环境
✅ 配置基于阈值的对比并支持抗锯齿检测

实现参考：

Skill:

.claude/skills/visual-regression-testing/SKILL.md

测试工具类:
```
tests/shared/imageTest.tsx
```
脚本:
```
scripts/visual-regression/
```

2. CI/CD Integration

2. CI/CD集成

Claude can integrate visual regression testing into GitHub Actions workflows with automated PR checks, baseline updates, and artifact management.

Capabilities:

✅ Create PR check workflows that fail on visual regression
✅ Automate baseline updates on main branch merges
✅ Generate and upload visual diff artifacts
✅ Post PR comments with visual comparison previews
✅ Configure parallel test execution for performance
✅ Set up report generation and distribution

Implementation Reference:

PR workflow:

.github/workflows/visual-regression-pr.yml

Baseline workflow:

.github/workflows/visual-regression-baseline.yml

Report workflow:

.github/workflows/visual-regression-report.yml

Claude可将视觉回归测试集成到GitHub Actions工作流中，实现自动化PR检查、基准更新和工件管理。

能力清单：

✅ 创建检测到视觉回归即失败的PR检查工作流
✅ 在主分支合并时自动更新基准
✅ 生成并上传视觉差异工件
✅ 在PR评论中发布视觉对比预览
✅ 配置并行测试执行以提升性能
✅ 搭建报告生成与分发机制

实现参考：

PR工作流:

.github/workflows/visual-regression-pr.yml

基准工作流:

.github/workflows/visual-regression-baseline.yml

报告工作流:

.github/workflows/visual-regression-report.yml

3. Screenshot Management

3. 截图管理

Claude can implement sophisticated screenshot capture and management systems with support for dynamic content masking, animation freezing, and viewport control.

Capabilities:

✅ Capture full-page and element-specific screenshots
✅ Auto-hide timestamps, dates, and other dynamic content
✅ Freeze animations and transitions for consistency
✅ Handle responsive design across multiple viewports
✅ Support theme variants (light/dark mode)
✅ Organize screenshots with semantic naming

Implementation Reference:

Baseline capture:

scripts/visual-regression/capture-baselines.ts

Test utilities:
```
tests/shared/imageTest.tsx:45-100
```

Claude可实现复杂的截图捕获与管理系统，支持动态内容遮罩、动画冻结和视口控制。

能力清单：

✅ 捕获整页和特定元素的截图
✅ 自动隐藏时间戳、日期等动态内容
✅ 冻结动画与过渡效果以保证一致性
✅ 处理多视口下的响应式设计
✅ 支持主题变体（亮色/暗色模式）
✅ 采用语义化命名组织截图

实现参考：

基准捕获:

scripts/visual-regression/capture-baselines.ts

测试工具类:
```
tests/shared/imageTest.tsx:45-100
```

4. Comparison and Reporting

4. 对比与报告

Claude can implement pixel-perfect comparison with configurable thresholds and generate comprehensive visual diff reports.

Capabilities:

✅ Pixel-by-pixel comparison using pixelmatch
✅ Configurable difference thresholds (0.01% to 5%)
✅ Anti-aliasing detection to reduce false positives
✅ Generate HTML reports with side-by-side comparisons
✅ Create Markdown reports for GitHub PR comments
✅ Track regression history and trends

Implementation Reference:

Comparison:

scripts/visual-regression/compare-screenshots.ts

HTML report:

scripts/visual-regression/generate-report.js

Claude可实现像素级精准对比，支持可配置阈值，并生成全面的视觉差异报告。

能力清单：

✅ 使用pixelmatch进行逐像素对比
✅ 可配置差异阈值（0.01%至5%）
✅ 抗锯齿检测以减少误报
✅ 生成带并排对比的HTML报告
✅ 为GitHub PR评论创建Markdown报告
✅ 追踪回归历史与趋势

实现参考：

对比逻辑:

scripts/visual-regression/compare-screenshots.ts

HTML报告:

scripts/visual-regression/generate-report.js

5. Cloud Storage Integration

5. 云存储集成

Claude can integrate visual regression artifacts with cloud storage providers for long-term archival and sharing.

Capabilities:

✅ Upload to AWS S3, Azure Blob Storage, or Alibaba OSS
✅ Generate public URLs for artifact sharing
✅ Implement retention policies
✅ Configure CDN distribution
✅ Support local storage for development

Implementation Reference:

Upload utility:

scripts/visual-regression/upload-to-storage.ts

Claude可将视觉回归工件与云存储提供商集成，实现长期归档与共享。

能力清单：

✅ 上传至AWS S3、Azure Blob Storage或阿里云OSS
✅ 生成工件共享的公开URL
✅ 实现保留策略
✅ 配置CDN分发
✅ 支持开发环境下的本地存储

实现参考：

上传工具类:

scripts/visual-regression/upload-to-storage.ts

Workflow Patterns

工作流模式

Pattern 1: Initial Setup

模式1：初始搭建

When a user requests visual regression testing setup, Claude will:

Create directory structure:

tests/shared/imageTest.tsx
scripts/visual-regression/
.github/workflows/visual-regression-*.yml
__image_snapshots__/baseline/

Install dependencies:

json

{
  "devDependencies": {
    "@playwright/test": "^1.40.0",
    "playwright": "^1.40.0",
    "jest-image-snapshot": "^6.2.0",
    "pixelmatch": "^5.3.0",
    "pngjs": "^7.0.0"
  }
}

Add npm scripts:

json

{
  "scripts": {
    "visual:test": "playwright test",
    "visual:baseline": "GENERATE_BASELINE=true playwright test --grep @baseline",
    "visual:update-baseline": "npm run visual:baseline",
    "visual:compare": "node scripts/visual-regression/compare-screenshots.ts",
    "visual:report": "node scripts/visual-regression/generate-report.js",
    "visual:upload": "node scripts/visual-regression/upload-to-storage.ts"
  }
}

Configure Playwright:

typescript

// playwright.config.ts
export default {
  testDir: './tests',
  use: {
    baseURL: 'http://localhost:5173',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
  ],
};

当用户请求视觉回归测试搭建时，Claude会：

创建目录结构：

tests/shared/imageTest.tsx
scripts/visual-regression/
.github/workflows/visual-regression-*.yml
__image_snapshots__/baseline/

安装依赖：

json

{
  "devDependencies": {
    "@playwright/test": "^1.40.0",
    "playwright": "^1.40.0",
    "jest-image-snapshot": "^6.2.0",
    "pixelmatch": "^5.3.0",
    "pngjs": "^7.0.0"
  }
}

添加npm脚本：

json

{
  "scripts": {
    "visual:test": "playwright test",
    "visual:baseline": "GENERATE_BASELINE=true playwright test --grep @baseline",
    "visual:update-baseline": "npm run visual:baseline",
    "visual:compare": "node scripts/visual-regression/compare-screenshots.ts",
    "visual:report": "node scripts/visual-regression/generate-report.js",
    "visual:upload": "node scripts/visual-regression/upload-to-storage.ts"
  }
}

配置Playwright：

typescript

// playwright.config.ts
export default {
  testDir: './tests',
  use: {
    baseURL: 'http://localhost:5173',
    screenshot: 'only-on-failure',
    video: 'retain-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
  ],
};

Pattern 2: Component Testing

模式2：组件测试

When adding visual tests for a new component:

Create test file:

typescript

import { test } from '@playwright/test';
import { runVisualTest, VIEWPORTS } from '../shared/imageTest';

test('button component - all variants', async ({ page }) => {
  await runVisualTest(page, {
    identifier: 'button-variants',
    url: '/components/button',
    viewport: VIEWPORTS.desktop,
    threshold: 0.05,
  });
});

Generate baseline:
bash
```
npm run visual:baseline
```
Run in CI:
- Automatically runs on PR creation
- Fails if visual differences detected
- Posts diff images in PR comment

为新组件添加视觉测试时：

创建测试文件：

typescript

import { test } from '@playwright/test';
import { runVisualTest, VIEWPORTS } from '../shared/imageTest';

test('button component - all variants', async ({ page }) => {
  await runVisualTest(page, {
    identifier: 'button-variants',
    url: '/components/button',
    viewport: VIEWPORTS.desktop,
    threshold: 0.05,
  });
});

生成基准：
bash
```
npm run visual:baseline
```
在CI中运行：
- 在PR创建时自动运行
- 检测到视觉差异则标记失败
- 在PR评论中发布差异图片

Pattern 3: Baseline Updates

模式3：基准更新

When intentional visual changes are made:

Review diff report:
- Check CI artifacts
- Download visual-report.html
- Verify changes are intentional

Update baselines:

bash

npm run visual:update-baseline
git add __image_snapshots__/baseline/
git commit -m "chore: update visual baselines for button redesign"

Push and re-test:
- CI re-runs tests
- Passes with updated baselines

当做出有意的视觉变更时：

查看差异报告：
- 检查CI工件
- 下载visual-report.html
- 验证变更为有意修改

更新基准：

bash

npm run visual:update-baseline
git add __image_snapshots__/baseline/
git commit -m "chore: update visual baselines for button redesign"

推送并重新测试：
- CI重新运行测试
- 使用更新后的基准通过测试

Pattern 4: Troubleshooting

模式4：故障排查

When visual tests fail unexpectedly:

Check for environmental differences:
- Font rendering (use Docker)
- Browser version (pin in CI)
- OS differences (test on same platform as CI)

Adjust thresholds if needed:

typescript

threshold: 0.1, // Increase from 0.05 to 0.1

Mask dynamic content:

typescript

hideSelectors: [
  '[data-testid="timestamp"]',
  '.loading-spinner',
],

当视觉测试意外失败时：

检查环境差异：
- 字体渲染（使用Docker）
- 浏览器版本（在CI中固定版本）
- 操作系统差异（在与CI相同的平台上测试）
必要时调整阈值：
typescript
```
threshold: 0.1, // 从0.05调整至0.1
```

遮罩动态内容：

typescript

hideSelectors: [
  '[data-testid="timestamp"]',
  '.loading-spinner',
],

Best Practices

最佳实践

1. What to Test

1. 测试范围

✅ Do test:

Critical user-facing components
Layout and responsive behavior
Theme variations (light/dark)
Multi-viewport rendering
Component state variants

❌ Don't test:

Frequently changing content (news feeds, timestamps)
Random/dynamic data displays
Third-party embedded content
Loading states with spinners

✅ 建议测试：

关键用户交互组件
布局与响应式表现
主题变体（亮色/暗色）
多视口渲染
组件状态变体

❌ 不建议测试：

频繁变化的内容（新闻流、时间戳）
随机/动态数据展示
第三方嵌入内容
带加载动画的状态

2. Threshold Configuration

2. 阈值配置

typescript

// Critical UI - strict comparison
threshold: 0.01  // 0.01% = ~10 pixels in 100k

// Standard components
threshold: 0.1   // 0.1% = ~100 pixels in 100k

// Charts/graphs with anti-aliasing
threshold: 0.5   // 0.5% = ~500 pixels in 100k

typescript

// 核心UI - 严格对比
threshold: 0.01  // 0.01% = 10万像素中约10个像素差异

// 标准组件
threshold: 0.1   // 0.1% = 10万像素中约100个像素差异

// 带抗锯齿的图表/图形
threshold: 0.5   // 0.5% = 10万像素中约500个像素差异

3. Performance Optimization

3. 性能优化

Run tests in parallel across workers
Use headless mode in CI
Cache Playwright browsers
Selectively test affected components
Reuse unchanged baselines

在多个工作进程中并行运行测试
在CI中使用无头模式
缓存Playwright浏览器
选择性测试受影响的组件
复用未变更的基准

4. False Positive Reduction

4. 减少误报

Freeze animations with CSS
Use consistent environment (Docker)
Pin browser versions
Mask timestamps and dynamic content
Enable anti-aliasing detection

使用CSS冻结动画
使用一致的环境（Docker）
固定浏览器版本
遮罩时间戳和动态内容
启用抗锯齿检测

Integration with Existing Tools

与现有工具的集成

Visual regression testing integrates with:

视觉回归测试可与以下工具集成：

Webapp Testing Skill

Webapp测试Skill

Uses
```
webapp-testing
```
skill for Playwright setup
Leverages
```
scripts/with_server.py
```
for server management
Follows reconnaissance-then-action pattern

Reference:

.claude/skills/webapp-testing/SKILL.md

使用
```
webapp-testing
```
skill进行Playwright搭建
借助
```
scripts/with_server.py
```
进行服务器管理
遵循“侦察-执行”模式

参考：

.claude/skills/webapp-testing/SKILL.md

CI/CD Pipelines

CI/CD流水线

Runs after unit/component tests pass
Blocks merges on visual regression
Uploads artifacts to GitHub Actions
Posts results in PR comments

Reference:

.github/workflows/visual-regression-pr.yml:1

在单元/组件测试通过后运行
检测到视觉回归时阻止合并
将工件上传至GitHub Actions
在PR评论中发布结果

参考：

.github/workflows/visual-regression-pr.yml:1

Odoo Development

Odoo开发

Can test Odoo web interface components
Supports multi-theme testing
Validates responsive layouts
Tests module-specific UI changes

可测试Odoo web界面组件
支持多主题测试
验证响应式布局
测试模块专属UI变更

Real-World Examples

实际案例

Example 1: Homepage Visual Test

案例1：首页视觉测试

typescript

import { test } from '@playwright/test';
import { runVisualTest, VIEWPORTS } from '../shared/imageTest';

test('homepage - responsive design', async ({ page }) => {
  for (const [name, viewport] of Object.entries(VIEWPORTS)) {
    await runVisualTest(page, {
      identifier: `homepage-${name}`,
      url: '/',
      viewport,
      fullPage: true,
      threshold: 0.1,
    });
  }
});

typescript

import { test } from '@playwright/test';
import { runVisualTest, VIEWPORTS } from '../shared/imageTest';

test('homepage - responsive design', async ({ page }) => {
  for (const [name, viewport] of Object.entries(VIEWPORTS)) {
    await runVisualTest(page, {
      identifier: `homepage-${name}`,
      url: '/',
      viewport,
      fullPage: true,
      threshold: 0.1,
    });
  }
});

Example 2: Component Library Test

案例2：组件库测试

typescript

test('design system - all components', async ({ page }) => {
  const components = ['button', 'input', 'select', 'modal', 'table'];

  for (const component of components) {
    await runVisualTest(page, {
      identifier: `component-${component}`,
      url: `/components/${component}`,
      selector: `[data-testid="${component}-showcase"]`,
      threshold: 0.05,
    });
  }
});

typescript

test('design system - all components', async ({ page }) => {
  const components = ['button', 'input', 'select', 'modal', 'table'];

  for (const component of components) {
    await runVisualTest(page, {
      identifier: `component-${component}`,
      url: `/components/${component}`,
      selector: `[data-testid="${component}-showcase"]`,
      threshold: 0.05,
    });
  }
});

Example 3: Theme Switching Test

案例3：主题切换测试

typescript

test('dark mode - all pages', async ({ page }) => {
  const pages = ['/', '/about', '/contact'];

  for (const pagePath of pages) {
    // Test light mode
    await runVisualTest(page, {
      identifier: `${pagePath.replace(/\//g, '-')}-light`,
      url: pagePath,
      fullPage: true,
    });

    // Switch to dark mode
    await page.evaluate(() => {
      document.documentElement.setAttribute('data-theme', 'dark');
    });

    // Test dark mode
    await runVisualTest(page, {
      identifier: `${pagePath.replace(/\//g, '-')}-dark`,
      url: pagePath,
      fullPage: true,
    });
  }
});

typescript

test('dark mode - all pages', async ({ page }) => {
  const pages = ['/', '/about', '/contact'];

  for (const pagePath of pages) {
    // 测试亮色模式
    await runVisualTest(page, {
      identifier: `${pagePath.replace(/\//g, '-')}-light`,
      url: pagePath,
      fullPage: true,
    });

    // 切换至暗色模式
    await page.evaluate(() => {
      document.documentElement.setAttribute('data-theme', 'dark');
    });

    // 测试暗色模式
    await runVisualTest(page, {
      identifier: `${pagePath.replace(/\//g, '-')}-dark`,
      url: pagePath,
      fullPage: true,
    });
  }
});

Learning Resources

学习资源

Official Documentation

官方文档

Industry Tools

行业工具

Argos CI - Visual testing platform
Percy - Visual review platform
Chromatic - Storybook visual testing

Argos CI - 视觉测试平台
Percy - 视觉评审平台
Chromatic - Storybook视觉测试工具

Implementation References

实现参考

All code is available in this repository:

.claude/skills/visual-regression-testing/SKILL.md

- Full skill documentation

.github/workflows/visual-regression-*.yml

- CI/CD workflows

```
tests/shared/imageTest.tsx
```
- Test utilities
```
scripts/visual-regression/
```
- Implementation scripts

所有代码可在本仓库中获取：

.claude/skills/visual-regression-testing/SKILL.md

- 完整Skill文档

.github/workflows/visual-regression-*.yml

- CI/CD工作流

```
tests/shared/imageTest.tsx
```
- 测试工具类
```
scripts/visual-regression/
```
- 实现脚本

When to Use This Capability

适用场景

Claude should proactively offer visual regression testing when:

User mentions visual testing or regression
- "I need to test UI changes"
- "How can I prevent visual bugs?"
- "Set up screenshot testing"
Component development context
- Building design systems
- Creating component libraries
- Implementing responsive layouts
CI/CD enhancement requests
- "Improve our testing pipeline"
- "Add automated UI checks"
- "Prevent visual bugs in PRs"
Debugging visual issues
- "Something looks different but I can't tell what"
- "UI broke on mobile but works on desktop"
- "Theme switching has issues"

当出现以下情况时，Claude应主动提供视觉回归测试服务：

用户提及视觉测试或回归相关内容
- "我需要测试UI变更"
- "如何预防视觉bug？"
- "搭建截图测试"
组件开发场景
- 构建设计系统
- 创建组件库
- 实现响应式布局
CI/CD增强需求
- "优化我们的测试流水线"
- "添加自动化UI检查"
- "防止PR中出现视觉bug"
视觉问题调试
- "看起来有变化但我找不到具体差异"
- "UI在移动端失效但桌面端正常"
- "主题切换存在问题"

Agent Decision Tree

Agent决策树

User request → Contains visual/UI/screenshot keywords?
  ├─ Yes → Offer visual regression testing setup
  │   ├─ Already has visual tests? → Enhance/extend
  │   └─ No visual tests? → Full setup
  │
  └─ No → Monitor for component development
      └─ Creating UI components? → Suggest visual testing

用户请求 → 包含视觉/UI/截图相关关键词？
  ├─ 是 → 提供视觉回归测试搭建服务
  │   ├─ 已拥有视觉测试？ → 增强/扩展现有能力
  │   └─ 无视觉测试？ → 完整搭建
  │
  └─ 否 → 监控组件开发场景
      └─ 是否正在创建UI组件？ → 建议使用视觉测试

Summary

总结

Claude has comprehensive capabilities for implementing production-grade visual regression testing infrastructure. This includes:

✅ Complete Playwright + jest-image-snapshot setup
✅ GitHub Actions CI/CD integration
✅ Automated baseline management
✅ Visual diff reporting with HTML/Markdown
✅ Multi-viewport and multi-browser support
✅ Cloud storage integration for artifacts
✅ Best practices from industry leaders (Ant Design, Argos)

All implementations follow proven patterns from leading design systems and are production-ready for immediate use.

Last Updated: 2025-11-13 Methodology Source: Ant Design Visual Regression Testing Implementation Status: ✅ Complete and production-ready

Claude具备实施生产级视觉回归测试基础设施的全面能力，包括：

✅ 完整的Playwright + jest-image-snapshot搭建
✅ GitHub Actions CI/CD集成
✅ 自动化基准管理
✅ 带HTML/Markdown输出的视觉差异报告
✅ 多视口和多浏览器支持
✅ 工件云存储集成
✅ 来自行业领导者（Ant Design、Argos）的最佳实践

所有实现均遵循领先设计系统的成熟模式，可直接投入生产使用。

最后更新： 2025-11-13 方法论来源： Ant Design视觉回归测试 实施状态： ✅ 已完成并可投入生产使用