frontend-bugfix

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"