216 lines
4.6 KiB
Markdown
216 lines
4.6 KiB
Markdown
---
|
||
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 层
|
||
|
||
```typescript
|
||
// 选项 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` 或类型断言
|
||
- 缺少必需字段
|
||
- 类型定义过时
|
||
|
||
**解决策略**：使用工厂函数
|
||
|
||
```typescript
|
||
const createMockData = (overrides?: Partial<DataType>): DataType => ({
|
||
id: 1,
|
||
name: 'default',
|
||
...overrides
|
||
});
|
||
```
|
||
|
||
### 3. 异步时序问题（8%）
|
||
|
||
**症状**：测试间歇性失败
|
||
|
||
**识别特征**：
|
||
|
||
- 缺少 `await`
|
||
- 使用 `getBy` 而非 `findBy`
|
||
- setTimeout 后立即断言
|
||
|
||
**解决策略**：正确等待
|
||
|
||
```typescript
|
||
// 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 | 不确定 | 停止收集信息 |
|
||
|
||
### 置信度计算
|
||
|
||
```text
|
||
置信度 = 证据质量(40%) + 模式匹配(30%) + 上下文完整性(20%) + 可复现性(10%)
|
||
```
|
||
|
||
**证据质量**：
|
||
|
||
- 高：有代码行号、堆栈、可复现
|
||
- 中：有错误信息但缺上下文
|
||
- 低：仅有模糊描述
|
||
|
||
**模式匹配**：
|
||
|
||
- 高：完全匹配已知模式
|
||
- 中：部分匹配
|
||
- 低：未知错误类型
|
||
|
||
**上下文完整性**：
|
||
|
||
- 高：测试代码 + 源代码 + 配置
|
||
- 中：只有测试或源代码
|
||
- 低：只有错误信息
|
||
|
||
**可复现性**：
|
||
|
||
- 高：稳定复现
|
||
- 中：偶发
|
||
- 低：环境相关
|
||
|
||
## TDD 流程
|
||
|
||
### RED Phase（写失败测试）
|
||
|
||
```typescript
|
||
// 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（最小实现）
|
||
|
||
```typescript
|
||
// 只写让测试通过的最小代码
|
||
// 不要优化，不要添加额外功能
|
||
```
|
||
|
||
### REFACTOR Phase（重构）
|
||
|
||
```typescript
|
||
// 改善代码结构
|
||
// 保持测试通过
|
||
// 消除重复
|
||
```
|
||
|
||
## 质量门禁
|
||
|
||
| 检查项 | 标准 |
|
||
| ---------- | ------ |
|
||
| 测试通过率 | 100% |
|
||
| 代码覆盖率 | >= 90% |
|
||
| 新代码覆盖率 | 100% |
|
||
| Lint | 无错误 |
|
||
| TypeCheck | 无错误 |
|
||
|
||
## 常用命令
|
||
|
||
```bash
|
||
# 运行前端测试
|
||
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"
|