测试修复标准

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

---

# 测试修复规范

## &#128203; 修复前审查清单

### 1. 问题分类
在修复测试失败前，必须先分类问题类型：

#### A. 测试代码问题（应该修复测试）
- ✅ 测试断言错误（例如：期望值设置错误）
- ✅ 测试数据问题（例如：测试数据不存在）
- ✅ 测试逻辑问题（例如：测试流程有误）
- ✅ 测试环境问题（例如：依赖服务未启动）

**修复原则**：修改测试代码，而不是业务代码

#### B. 业务代码问题（应该修复业务）
- ✅ 功能逻辑错误（例如：计算错误、逻辑判断错误）
- ✅ 数据验证错误（例如：参数验证不严格）
- ✅ API 返回错误（例如：返回格式不对）
- ✅ 类型定义错误（例如：类型不匹配）

**修复原则**：修改业务代码，确保功能正确

#### C. 浮点数精度问题
- ✅ 数据库返回 `1500.00`，测试期望 `1500`
- ✅ 日期时间精度差异

**修复原则**：
- **方案1**：使用 `parseFloat()` 或 `Number()` 规范化
- **方案2**：使用 `toBeCloseTo()` 而不是 `toBe()`
- **方案3**：使用 `Math.abs(actual - expected) < epsilon` 比较

---

## &#127919; 修复规范

### 1. 单元测试修复

#### 规范 1.1：修复测试代码优先
```
❌ 错误：修改业务代码来通过测试
// 如果业务代码是正确的，但测试断言错误
balance = 1500.00 // ❌ 强制修改业务代码

✅ 正确：修改测试断言
expect(balance).toBe(parseFloat('1500.00')) // ✅ 修正测试断言
```

#### 规范 1.2：浮点数比较
```
❌ 错误：直接比较浮点数
expect(balance).toBe(1500.00)

✅ 正确：使用精度比较
expect(balance).toBeCloseTo(1500, 2) // 保留2位小数
// 或
expect(parseFloat(balance)).toBe(1500)
```

#### 规范 1.3：清理测试数据
```
✅ 每个测试结束后清理数据
afterEach(async () => {
  await cleanupTestData()
})
```

---

### 2. API 测试修复

#### 规范 2.1：检查测试数据
```
// 创建测试数据
const tenant = await createTenant(tenantData)
const tenantId = tenant.id

// 立即查询验证
const found = await getTenantById(tenantId)
expect(found).toBeDefined()

// 如果失败，先检查：
// 1. 数据是否真的创建了？
console.log('Created tenant:', tenant)
// 2. 查询条件是否正确？
console.log('Searching for ID:', tenantId)
```

#### 规范 2.2：异步处理
```
❌ 错误：不等待异步操作
const tenant = createTenant(data)
const found = getTenantById(tenant.id) // ❌ tenant 可能还是 undefined

✅ 正确：使用 await
const tenant = await createTenant(data)
const found = await getTenantById(tenant.id) // ✅ 确保数据已创建
```

#### 规范 2.3：错误处理
```
✅ 测试错误情况
await expect(
  createTenant(invalidData)
).rejects.toThrow('ValidationError')

❌ 不要只测试成功情况
const tenant = await createTenant(data) // 只测试成功
```

---

### 3. 类型错误修复

#### 规范 3.1：添加类型定义
```typescript
// 缺少类型定义的包
declare module 'miniprogram-sm-crypto' {
  export function encrypt(data: string, key: string): string
  export function decrypt(data: string, key: string): string
}

// 或安装类型定义
pnpm add -D @types/miniprogram-sm-crypto
```

#### 规范 3.2：避免使用 any
```typescript
❌ 错误：使用 any
const result: any = await getData()

✅ 正确：使用具体类型
interface DataResult {
  id: string
  name: string
}
const result: DataResult = await getData()
```

#### 规范 3.3：Drizzle ORM 类型
```typescript
❌ 错误：直接传类型不匹配的值
db.insert(tenants).values({
  balance: 1500, // ❌ balance 是 string 类型
})

✅ 正确：转换为字符串
db.insert(tenants).values({
  balance: String(1500), // ✅ 转换为字符串
})

✅ 或修改 schema 定义
balance: text('balance').notNull().$type<number>(), // 类型为 number，存储为 text
```

---

## &#128202; 修复决策树

```
测试失败
  ↓
是测试代码问题吗？
  ├─ 是 → 修改测试代码
  │         ├─ 修正断言
  │         ├─ 修正测试数据
  │         └─ 修正测试逻辑
  │
  └─ 否 → 是业务代码问题吗？
            ├─ 是 → 修改业务代码
            │         ├─ 修复逻辑错误
            │         ├─ 添加验证
            │         └─ 修正返回格式
            │
            └─ 否 → 是类型问题吗？
                      ├─ 是 → 添加类型定义或修正类型
                      └─ 否 → 检查环境配置
```

---

## ✅ 修复检查清单

修复完成后，必须检查：

- [ ] 测试通过（绿色）
- [ ] 没有破坏其他测试
- [ ] 业务逻辑仍然正确
- [ ] 类型检查通过（如果修复了类型问题）
- [ ] 代码审查通过（自己检查）
- [ ] 提交信息清晰描述修复内容

---

## &#128221; 提交信息规范

修复测试时，提交信息应遵循：

### 格式
```
<type>(<scope>): <subject>

<body>
```

### 类型
- `fix`: 修复 bug
- `test`: 修复测试代码
- `refactor`: 重构代码
- `types`: 修复类型定义

### 示例
```
fix(unit): 修复租户余额测试的浮点数精度问题

- 使用 parseFloat() 规范化浮点数比较
- 修改测试断言为 toBeCloseTo()
```

```
test(api): 修复租户查询测试的数据问题

- 添加 await 确保数据创建完成
- 添加调试日志输出
- 修复查询条件错误
```

```
types(services): 添加缺失的依赖包类型定义

- 添加 miniprogram-sm-crypto 类型声明
- 添加 wechat-api 类型声明
```

---

## &#128683; 修复禁忌

### ❌ 不要做的事情

1. **不要删除测试**
   - 如果测试一直失败，找出原因，不要删除它

2. **不要忽略错误**
   - 不要添加 `// eslint-disable-next-line` 来忽略问题

3. **不要修改类型检查配置**
   - 不要为了通过测试而修改 `tsconfig.json`

4. **不要硬编码测试结果**
   - 不要 `expect(result).toBe('hardcoded value')`

5. **不要只修改测试而不验证业务逻辑**
   - 测试通过了，但功能是否正确？

### ✅ 应该做的事情

1. **先理解问题**
   - 为什么测试失败？
   - 是测试问题还是业务问题？

2. **定位根本原因**
   - 使用调试日志
   - 查看错误堆栈
   - 验证假设

3. **最小化修改**
   - 只修改必要的代码
   - 保持代码简洁

4. **添加测试保护**
   - 修复后添加边界测试
   - 添加回归测试

5. **文档化修复**
   - 记录修复原因
   - 更新相关文档

---

## &#127891; 最佳实践

### 1. 逐步修复
```
不要一次修复所有问题
应该：
1. 修复最简单的问题（例如：精度问题）
2. 验证通过
3. 修复下一个问题
4. 重复
```

### 2. 使用调试日志
```typescript
console.log('[TEST] Created tenant:', tenant)
console.log('[TEST] Query result:', result)
console.log('[TEST] Expected:', expected)
console.log('[TEST] Actual:', actual)
```

### 3. 分离关注点
```
如果一个问题涉及多个模块：
- 先修复核心问题
- 再修复相关问题
- 最后优化代码
```

### 4. 验证修复
```
修复后：
1. 运行失败的测试
2. 运行所有测试（确保没有破坏其他测试）
3. 运行类型检查
4. 运行代码检查
```

---

## &#128218; 参考资料

- [Jest 测试最佳实践](https://jestjs.io/docs/tutorial-react-native)
- [TypeScript 类型定义](https://www.typescriptlang.org/docs/handbook/declaration-files/do-s-and-don-ts.html)
- [Drizzle ORM 类型](https://orm.drizzle.team/docs/good-practices)