everything-claude-code/docs/zh-CN/skills/ai-regression-testing/SKILL.md

name, description, origin

name	description	origin
ai-regression-testing	AI辅助开发的回归测试策略。沙盒模式API测试，无需依赖数据库，自动化的缺陷检查工作流程，以及捕捉AI盲点的模式，其中同一模型编写和审查代码。	ECC

AI 回归测试

专为 AI 辅助开发设计的测试模式，其中同一模型编写代码并审查代码——这会形成系统性的盲点，只有自动化测试才能发现。

何时激活

• AI 代理（Claude Code、Cursor、Codex）已修改 API 路由或后端逻辑
• 发现并修复了一个 bug——需要防止重新引入
• 项目具有沙盒/模拟模式，可用于无需数据库的测试
• 在代码更改后运行 /bug-check 或类似的审查命令
• 存在多个代码路径（沙盒与生产环境、功能开关等）

核心问题

当 AI 编写代码然后审查其自身工作时，它会将相同的假设带入这两个步骤。这会形成一个可预测的失败模式：

AI writes fix → AI reviews fix → AI says "looks correct" → Bug still exists

实际示例（在生产环境中观察到）：

Fix 1: Added notification_settings to API response
  → Forgot to add it to the SELECT query
  → AI reviewed and missed it (same blind spot)

Fix 2: Added it to SELECT query
  → TypeScript build error (column not in generated types)
  → AI reviewed Fix 1 but didn't catch the SELECT issue

Fix 3: Changed to SELECT *
  → Fixed production path, forgot sandbox path
  → AI reviewed and missed it AGAIN (4th occurrence)

Fix 4: Test caught it instantly on first run ✅

模式：沙盒/生产环境路径不一致是 AI 引入的 #1 回归问题。

沙盒模式 API 测试

大多数具有 AI 友好架构的项目都有一个沙盒/模拟模式。这是实现快速、无需数据库的 API 测试的关键。

设置（Vitest + Next.js App Router）

// vitest.config.ts
import { defineConfig } from "vitest/config";
import path from "path";

export default defineConfig({
  test: {
    environment: "node",
    globals: true,
    include: ["__tests__/**/*.test.ts"],
    setupFiles: ["__tests__/setup.ts"],
  },
  resolve: {
    alias: {
      "@": path.resolve(__dirname, "."),
    },
  },
});

// __tests__/setup.ts
// Force sandbox mode — no database needed
process.env.SANDBOX_MODE = "true";
process.env.NEXT_PUBLIC_SUPABASE_URL = "";
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY = "";

Next.js API 路由的测试辅助工具

// __tests__/helpers.ts
import { NextRequest } from "next/server";

export function createTestRequest(
  url: string,
  options?: {
    method?: string;
    body?: Record<string, unknown>;
    headers?: Record<string, string>;
    sandboxUserId?: string;
  },
): NextRequest {
  const { method = "GET", body, headers = {}, sandboxUserId } = options || {};
  const fullUrl = url.startsWith("http") ? url : `http://localhost:3000${url}`;
  const reqHeaders: Record<string, string> = { ...headers };

  if (sandboxUserId) {
    reqHeaders["x-sandbox-user-id"] = sandboxUserId;
  }

  const init: { method: string; headers: Record<string, string>; body?: string } = {
    method,
    headers: reqHeaders,
  };

  if (body) {
    init.body = JSON.stringify(body);
    reqHeaders["content-type"] = "application/json";
  }

  return new NextRequest(fullUrl, init);
}

export async function parseResponse(response: Response) {
  const json = await response.json();
  return { status: response.status, json };
}

编写回归测试

关键原则：为已发现的 bug 编写测试，而不是为正常工作的代码编写测试。

// __tests__/api/user/profile.test.ts
import { describe, it, expect } from "vitest";
import { createTestRequest, parseResponse } from "../../helpers";
import { GET, PATCH } from "@/app/api/user/profile/route";

// Define the contract — what fields MUST be in the response
const REQUIRED_FIELDS = [
  "id",
  "email",
  "full_name",
  "phone",
  "role",
  "created_at",
  "avatar_url",
  "notification_settings",  // ← Added after bug found it missing
];

describe("GET /api/user/profile", () => {
  it("returns all required fields", async () => {
    const req = createTestRequest("/api/user/profile");
    const res = await GET(req);
    const { status, json } = await parseResponse(res);

    expect(status).toBe(200);
    for (const field of REQUIRED_FIELDS) {
      expect(json.data).toHaveProperty(field);
    }
  });

  // Regression test — this exact bug was introduced by AI 4 times
  it("notification_settings is not undefined (BUG-R1 regression)", async () => {
    const req = createTestRequest("/api/user/profile");
    const res = await GET(req);
    const { json } = await parseResponse(res);

    expect("notification_settings" in json.data).toBe(true);
    const ns = json.data.notification_settings;
    expect(ns === null || typeof ns === "object").toBe(true);
  });
});

测试沙盒/生产环境一致性

最常见的 AI 回归问题：修复了生产环境路径但忘记了沙盒路径（或反之）。

// Test that sandbox responses match the expected contract
describe("GET /api/user/messages (conversation list)", () => {
  it("includes partner_name in sandbox mode", async () => {
    const req = createTestRequest("/api/user/messages", {
      sandboxUserId: "user-001",
    });
    const res = await GET(req);
    const { json } = await parseResponse(res);

    // This caught a bug where partner_name was added
    // to production path but not sandbox path
    if (json.data.length > 0) {
      for (const conv of json.data) {
        expect("partner_name" in conv).toBe(true);
      }
    }
  });
});

将测试集成到 Bug 检查工作流中

自定义命令定义

<!-- .claude/commands/bug-check.md -->
# Bug 检查

## 步骤 1：自动化测试（强制，不可跳过）

在代码审查前**首先**运行以下命令：

    npm run test       # Vitest 测试套件
    npm run build      # TypeScript 类型检查 + 构建

- 如果测试失败 → 报告为最高优先级 Bug
- 如果构建失败 → 将类型错误报告为最高优先级
- 只有在两者都通过后，才能继续到步骤 2

## 步骤 2：代码审查（AI 审查）

1. 沙盒/生产环境路径一致性
2. API 响应结构是否符合前端预期
3. SELECT 子句的完整性
4. 包含回滚的错误处理
5. 乐观更新的竞态条件

## 步骤 3：对于每个修复的 Bug，提出回归测试方案

工作流程

User: "バグチェックして" (or "/bug-check")
  │
  ├─ Step 1: npm run test
  │   ├─ FAIL → Bug found mechanically (no AI judgment needed)
  │   └─ PASS → Continue
  │
  ├─ Step 2: npm run build
  │   ├─ FAIL → Type error found mechanically
  │   └─ PASS → Continue
  │
  ├─ Step 3: AI code review (with known blind spots in mind)
  │   └─ Findings reported
  │
  └─ Step 4: For each fix, write a regression test
      └─ Next bug-check catches if fix breaks

常见的 AI 回归模式

模式 1：沙盒/生产环境路径不匹配

频率：最常见（在 4 个回归问题中观察到 3 个）

// ❌ AI adds field to production path only
if (isSandboxMode()) {
  return { data: { id, email, name } };  // Missing new field
}
// Production path
return { data: { id, email, name, notification_settings } };

// ✅ Both paths must return the same shape
if (isSandboxMode()) {
  return { data: { id, email, name, notification_settings: null } };
}
return { data: { id, email, name, notification_settings } };

用于捕获它的测试：

it("sandbox and production return same fields", async () => {
  // In test env, sandbox mode is forced ON
  const res = await GET(createTestRequest("/api/user/profile"));
  const { json } = await parseResponse(res);

  for (const field of REQUIRED_FIELDS) {
    expect(json.data).toHaveProperty(field);
  }
});

模式 2：SELECT 子句遗漏

频率：在使用 Supabase/Prisma 添加新列时常见

// ❌ New column added to response but not to SELECT
const { data } = await supabase
  .from("users")
  .select("id, email, name")  // notification_settings not here
  .single();

return { data: { ...data, notification_settings: data.notification_settings } };
// → notification_settings is always undefined

// ✅ Use SELECT * or explicitly include new columns
const { data } = await supabase
  .from("users")
  .select("*")
  .single();

模式 3：错误状态泄漏

频率：中等——当向现有组件添加错误处理时

// ❌ Error state set but old data not cleared
catch (err) {
  setError("Failed to load");
  // reservations still shows data from previous tab!
}

// ✅ Clear related state on error
catch (err) {
  setReservations([]);  // Clear stale data
  setError("Failed to load");
}

模式 4：乐观更新未正确回滚

// ❌ No rollback on failure
const handleRemove = async (id: string) => {
  setItems(prev => prev.filter(i => i.id !== id));
  await fetch(`/api/items/${id}`, { method: "DELETE" });
  // If API fails, item is gone from UI but still in DB
};

// ✅ Capture previous state and rollback on failure
const handleRemove = async (id: string) => {
  const prevItems = [...items];
  setItems(prev => prev.filter(i => i.id !== id));
  try {
    const res = await fetch(`/api/items/${id}`, { method: "DELETE" });
    if (!res.ok) throw new Error("API error");
  } catch {
    setItems(prevItems);  // Rollback
    alert("削除に失敗しました");
  }
};

策略：在发现 Bug 的地方进行测试

不要追求 100% 的覆盖率。相反：

Bug found in /api/user/profile     → Write test for profile API
Bug found in /api/user/messages    → Write test for messages API
Bug found in /api/user/favorites   → Write test for favorites API
No bug in /api/user/notifications  → Don't write test (yet)

为什么这在 AI 开发中有效：

1. AI 倾向于重复犯同一类错误
2. Bug 集中在复杂区域（身份验证、多路径逻辑、状态管理）
3. 一旦经过测试，该特定回归问题就不会再次发生
4. 测试数量随着 Bug 修复而有机增长——没有浪费精力

快速参考

AI 回归模式	测试策略	优先级
沙盒/生产环境不匹配	断言沙盒模式下响应结构相同	🔴 高
SELECT 子句遗漏	断言响应中包含所有必需字段	🔴 高
错误状态泄漏	断言出错时状态已清理	🟡 中
缺少回滚	断言 API 失败时状态已恢复	🟡 中
类型转换掩盖 null	断言字段不为 undefined	🟡 中

要 / 不要

要：

• 发现 bug 后立即编写测试（如果可能，在修复之前）
• 测试 API 响应结构，而不是实现细节
• 将运行测试作为每次 bug 检查的第一步
• 保持测试快速（在沙盒模式下总计 < 1 秒）
• 以测试所预防的 bug 来命名测试（例如，"BUG-R1 regression"）

不要：

• 为从未出现过 bug 的代码编写测试
• 相信 AI 自我审查可以作为自动化测试的替代品
• 因为“只是模拟数据”而跳过沙盒路径测试
• 在单元测试足够时编写集成测试
• 追求覆盖率百分比——追求回归预防