agent-capabilities

Name: agent-capabilities
Author: jgtolentino

github.com/jgtolentino测试与质量2258 次安装33 周前更新

代码仓库

关于 agent-capabilities

面向 Claude 的 Web 应用视觉回归测试技能，涵盖截图、图像比较、报告和 CI 工作流，适合验证界面变更的开发团队。

主要功能

01配置 Playwright 视觉测试
02管理基准截图
03逐像素图像比较
04生成 HTML 和 Markdown 差异报告
05集成 GitHub Actions
06屏蔽动态内容

适用场景

01在 Pull Request 中检查界面变更
02测试响应式布局和主题
03设计改版后更新截图基准

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/jgtolentino/insightpulse-odoo --skill agent-capabilities

安装后在 Claude Code 中输入/agent-capabilities确认已加载。

附带文件VISUAL_REGRESSION_INTEGRATION.md

详细介绍

Agent 能力 - 视觉回归测试

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

核心能力

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

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

能力：

✅ 配置 Playwright 进行视觉测试
✅ 实现 jest-image-snapshot，进行像素级精确比对
✅ 创建基线截图管理系统
✅ 生成 HTML/Markdown 格式的视觉差异报告
✅ 设置多视口和多浏览器测试
✅ 配置基于阈值的比对，并检测抗锯齿

实现参考：

技能：.claude/skills/visual-regression-testing/SKILL.md
测试工具：tests/shared/imageTest.tsx
脚本：scripts/visual-regression/

2. CI/CD 集成

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. 截图管理

Claude 可以实现完善的截图采集和管理系统，支持动态内容遮罩、动画冻结和视口控制。

能力：

✅ 捕获整页截图和特定元素的截图
✅ 自动隐藏时间戳、日期及其他动态内容
✅ 冻结动画和过渡效果，以确保一致性
✅ 在多个视口下处理响应式设计
✅ 支持主题变体（浅色/深色模式）
✅ 使用语义化名称整理截图

实现参考：

基线采集：scripts/visual-regression/capture-baselines.ts
测试工具：tests/shared/imageTest.tsx:45-100

4. 比对和报告

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

能力：

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

实现参考：

比对：scripts/visual-regression/compare-screenshots.ts
HTML 报告：scripts/visual-regression/generate-report.js

5. 云存储集成

Claude 可以将视觉回归构建产物集成到云存储服务提供商，以便长期归档和共享。

能力：

✅ 上传到 AWS S3、Azure Blob Storage 或 Alibaba OSS
✅ 为共享构建产物生成公开 URL
✅ 实施保留策略
✅ 配置 CDN 分发
✅ 支持开发期间使用本地存储

实现参考：

上传工具：scripts/visual-regression/upload-to-storage.ts

工作流模式

模式 1：初始设置

当用户请求设置视觉回归测试时，Claude 将：

创建目录结构：

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

安装依赖：

{
  "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 脚本：

{
  "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：

// 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'] } },
  ],
};

模式 2：组件测试

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

创建测试文件：

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,
  });
});

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

模式 3：基线更新

进行有意的视觉更改时：

查看差异报告：
- 检查 CI 构建产物
- 下载 visual-report.html
- 验证更改是否符合预期

更新基线：

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

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

模式 4：故障排查

视觉测试意外失败时：

检查环境差异：
- 字体渲染（使用 Docker）
- 浏览器版本（在 CI 中固定版本）
- 操作系统差异（在与 CI 相同的平台上测试）

根据需要调整阈值：

threshold: 0.1, // Increase from 0.05 to 0.1

屏蔽动态内容：

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

最佳实践

1. 测试内容

✅ 应测试：

面向用户的关键组件
布局和响应式行为
主题变体（浅色/深色）
多视口渲染
组件状态变体

❌ 不应测试：

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

2. 阈值配置

// 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

3. 性能优化

在多个工作进程间并行运行测试
在 CI 中使用无头模式
缓存 Playwright 浏览器
仅测试受影响的组件
重用未更改的基线

4. 减少误报

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

与现有工具集成

视觉回归测试可与以下内容集成：

Web 应用测试技能

使用 webapp-testing 技能配置 Playwright
利用 scripts/with_server.py 管理服务
遵循先侦察、后操作的模式

参考： .claude/skills/webapp-testing/SKILL.md

CI/CD 流水线

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

参考： .github/workflows/visual-regression-pr.yml:1

Odoo 开发

可测试 Odoo Web 界面组件
支持多主题测试
验证响应式布局
测试特定模块的 UI 更改

实际示例

示例 1：首页视觉测试

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,
    });
  }
});

示例 2：组件库测试

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,
    });
  }
});

示例 3：主题切换测试

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,
    });
  }
});

学习资源

官方文档

行业工具

Argos CI - 视觉测试平台
Percy - 视觉审查平台
Chromatic - Storybook 视觉测试

实现参考

所有代码均可在此仓库中找到：

.claude/skills/visual-regression-testing/SKILL.md - 完整技能文档
.github/workflows/visual-regression-*.yml - CI/CD 工作流
tests/shared/imageTest.tsx - 测试工具
scripts/visual-regression/ - 实现脚本

适用场景

Claude 应在以下情况下主动推荐视觉回归测试：

用户提到视觉测试或回归
- “我需要测试 UI 更改”
- “如何防止视觉 Bug？”
- “设置截图测试”
组件开发场景
- 构建设计系统
- 创建组件库
- 实现响应式布局
CI/CD 改进请求
- “改进我们的测试流水线”
- “添加自动化 UI 检查”
- “防止 PR 中出现视觉 Bug”
调试视觉问题
- “有些地方看起来不一样，但我看不出来”
- “UI 在移动端出问题，但在桌面端正常”
- “主题切换有问题”

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

总结

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

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

所有实施方案均遵循领先设计系统验证过的模式，可立即用于生产环境。

上次更新： 2025-11-13 方法论来源： Ant Design 视觉回归测试 实施状态： ✅ 已完成，可用于生产环境

支持 Markdown

登录后评论

基本信息

作者: jgtolentino
仓库: jgtolentino/insightpulse-odoo
分类: 测试与质量
安装次数: 58
GitHub Stars: 22

报告问题