Skip to main content

在每次 PR 之前捕捉视觉回归问题

一种仓库技能,可让 Devin 在打开 PR 之前,对每个受影响的页面进行截图并标记布局错乱问题。
AuthorCognition
Category功能开发
FeaturesSkills
1

问题:CSS Bug 容易逃过单元测试

你的测试套件全部通过,CI 全绿,PR 也已经合并 —— 但现在设置页面在移动端出现文字重叠,结账按钮被页脚挡住了。单元测试和 linter 无法捕捉这类视觉问题,于是问题被带到生产环境,最后由客户来反馈。一个仓库级 skill 可以解决这个问题。Skills 是你提交到任意仓库中 .agents/skills/<your-skill>/ 路径下的 markdown 文件。Devin 能看到所有已连接仓库中的全部 skills —— 你可以手动触发它们,或者当 Devin 检测到相关场景时,由 Devin 自动选择触发。这个 skill 会精确告诉 Devin 如何启动你的应用、如何访问受 diff 影响的页面,并在多个视口宽度下为这些页面截图 —— 每一次、在每个 PR 之前都会执行。
2

将 visual-regression 技能添加到你的代码库

.agents/skills/visual-regression/visual-regression.md 中提交一个文件,将你团队的手动 QA 检查清单编写为 Devin 可以遵循的步骤:
# 视觉回归检查

## 描述
在提交任何 PR(拉取请求)之前,请在本地启动应用程序,并对当前差异所影响的每个页面分别在桌面端和移动端宽度下截图。标记发现的任何布局问题。

## 前提条件
- Docker 正在运行(用于数据库)
- 端口 3000 可用

## 设置
1. 安装依赖项:`npm install`
2. 启动服务:`docker-compose up -d postgres redis`
3. 运行迁移:`npx prisma migrate dev`
4. 写入测试数据:`npm run db:seed`
5. 启动开发服务器:`npm run dev`
6. 等待终端中出现 "Ready on http://localhost:3000"

## 视觉检查
1. 读取当前 git diff,确定哪些页面受到影响
2. 对每个受影响的页面:
   a. 在浏览器中打开 http://localhost:3000/{route}
   b. 在 1280px 宽度(桌面端)下截图
   c. 将浏览器调整为 375px 宽度(移动端)
   d. 在移动端宽度下截图
   e. 检查以下问题:文字重叠、元素被其他元素遮挡、出现水平滚动条、按钮或链接无法点击、图片或图标缺失、控制台报错
3. 如发现任何问题,请记录页面 URL、视口宽度及问题描述

## 提交 PR 前
1. 运行 `npm run lint` 并修复所有问题
2. 运行 `npm test` 并确认所有测试通过
3. 在 PR 描述中附上所有截图
4. 如发现问题,请在 PR 正文顶部列出
此文件会随你的代码一起分发。一旦提交,Devin 就会将其视为一项可用技能——每当有会话涉及此仓库中的 UI 文件时,Devin 都可以自动触发视觉回归检查,或者你也可以在任意时间点手动执行这些检查。
3

使检查针对你的各个页面

像 “check the page looks right” 这样的笼统指令会产生模糊的结果。这个技能中最有价值的部分,是告诉 Devin 在你应用的每个部分中,什么才算是「正确」的表现。在你的技能中添加针对特定路由的单独小节:
## Route-Specific Checks

### Dashboard (`/dashboard`)
- The metric cards should display in a 3-column grid on desktop
- Cards should stack to a single column on mobile
- The chart should be fully visible without horizontal scroll

### Checkout (`/checkout`)
- The "Place Order" button must be visible without scrolling
  on both desktop and mobile
- The order summary sidebar should collapse into an accordion on mobile
- The price breakdown should show subtotal, tax, and total on separate lines

### Settings (`/settings`)
- All form labels should be left-aligned with their inputs
- The "Save" button must be reachable at the bottom of the form
- Tab navigation between sections should update the URL hash
Devin 会读取 diff,识别哪些路由受到影响,并跟进对应部分——从而让检查更有针对性,而不是泛泛而为。
4

看看它如何发现实际的回归问题

假设一名工程师为了实现响应式布局,把仪表盘上的 CSS grid 从 grid-template-columns: repeat(3, 1fr) 改成了 repeat(auto-fit, minmax(200px, 1fr))。单元测试全部通过——逻辑没有任何改动。但在移动端,这些卡片现在会溢出视口。当 Devin 完成这次代码修改后,它会自动按该技能执行以下步骤:
  1. 启动应用 —— 安装依赖、启动 Docker、运行数据库迁移、灌入数据、启动开发服务器
  2. 阅读 diff —— 发现 src/components/Dashboard.tsx 被修改,将其映射到 /dashboard 路由
  3. 在 1280px 截图 —— 3 列网格渲染正确
  4. 在 375px 截图 —— 发现水平溢出:卡片在视口内放不下
  5. 标记问题 —— 报告 “Horizontal scroll detected on /dashboard at 375px width — metric cards overflow the viewport”
  6. 修复 CSS —— 添加 overflow-x: hidden,并把 minmax 的最小值调整为 150px
  7. 重新截图 —— 在两个宽度下都确认修复生效
  8. 打开 PR —— 在描述中附上修复前/修复后的截图和变更说明
你可以在你的会话工作区中,通过浏览器标签页实时看到整个过程。
5

扩展到你的技术栈

根据你的项目,扩展该技能以支持额外的工具和验证步骤: