---

name: frontend-bugfix description: | Use this skill when debugging frontend test failures (React/TypeScript, Vitest, etc.), fixing bugs in React/TypeScript code, or following TDD methodology for frontend bug fixes. This skill provides the complete bugfix workflow knowledge including error classification, confidence scoring, and TDD best practices. version: 2.1.0

Frontend Bugfix Workflow Skill

本 skill 提供前端测试 bugfix 的完整工作流知识，包括错误分类体系、置信度评分系统和 TDD 最佳实践。

错误分类体系

前端测试失败主要分为以下类型（按频率排序）：

1. Mock 层次冲突（71%）

症状：Mock 不生效，组件行为异常

识别特征：

• 同时存在 vi.mock 和 server.use
• Hook 返回值与预期不符
• API 调用未被拦截

解决策略：选择单一 Mock 层

// 选项 A：HTTP Mock（推荐用于集成测试）
server.use(
  http.get('/api/data', () => HttpResponse.json({ data: 'test' }))
);

// 选项 B：Hook Mock（用于单元测试）
vi.mock('@/hooks/useData', () => ({
  useData: () => ({ data: 'test', isLoading: false })
}));

2. TypeScript 类型不匹配（15%）

症状：类型错误、Mock 数据不完整

识别特征：

• as any 或类型断言
• 缺少必需字段
• 类型定义过时

解决策略：使用工厂函数

const createMockData = (overrides?: Partial<DataType>): DataType => ({
  id: 1,
  name: 'default',
  ...overrides
});

3. 异步时序问题（8%）

症状：测试间歇性失败

识别特征：

• 缺少 await
• 使用 getBy 而非 findBy
• setTimeout 后立即断言

解决策略：正确等待

// Before
render(<Component />);
expect(screen.getByText('Loaded')).toBeInTheDocument();

// After
render(<Component />);
expect(await screen.findByText('Loaded')).toBeInTheDocument();

4. 组件渲染问题（4%）

症状：组件未按预期渲染

识别特征：

• 条件渲染不触发
• 状态更新未反映
• Props 传递错误

解决策略：验证渲染条件和状态

5. Hook 缓存依赖问题（2%）

症状：Hook 返回过时数据

识别特征：

• useEffect 依赖数组不完整
• useMemo/useCallback 缓存问题
• 闭包陷阱

解决策略：检查并修复依赖数组

置信度评分系统

评分标准（0-100）

分数	级别	行为
80+	高	自动执行
60-79	中	标记验证后继续
40-59	低	暂停询问用户
<40	不确定	停止收集信息

置信度计算

置信度 = 证据质量(40%) + 模式匹配(30%) + 上下文完整性(20%) + 可复现性(10%)

证据质量：

• 高：有代码行号、堆栈、可复现
• 中：有错误信息但缺上下文
• 低：仅有模糊描述

模式匹配：

• 高：完全匹配已知模式
• 中：部分匹配
• 低：未知错误类型

上下文完整性：

• 高：测试代码 + 源代码 + 配置
• 中：只有测试或源代码
• 低：只有错误信息

可复现性：

• 高：稳定复现
• 中：偶发
• 低：环境相关

TDD 流程

RED Phase（写失败测试）

// 1. 明确期望行为
it('should display error when API fails', async () => {
  // 2. 设置失败场景
  server.use(
    http.get('/api/data', () => HttpResponse.error())
  );

  // 3. 渲染组件
  render(<DataComponent />);

  // 4. 断言期望结果
  expect(await screen.findByText('Error loading data')).toBeInTheDocument();
});

GREEN Phase（最小实现）

// 只写让测试通过的最小代码
// 不要优化，不要添加额外功能

REFACTOR Phase（重构）

// 改善代码结构
// 保持测试通过
// 消除重复

质量门禁

检查项	标准
测试通过率	100%
代码覆盖率	>= 90%
新代码覆盖率	100%
Lint	无错误
TypeCheck	无错误

常用命令

# 运行前端测试
make test TARGET=frontend

# 运行特定测试
make test TARGET=frontend FILTER=ComponentName

# 覆盖率检查
make test TARGET=frontend MODE=coverage

# 完整 QA
make qa

相关文档

文档路径由配置指定（best_practices_dir），使用以下关键词搜索：

• 测试最佳实践：关键词 "testing", "best-practices"
• Mock 策略：关键词 "mock", "msw", "vi.mock"
• 问题诊断：关键词 "troubleshooting", "debugging"
• 实现指南：关键词 "implementation", "guide"