yys-editor/docs/testing-rules.md

# 测试规范

## 核心原则

**所有涉及数据层和业务逻辑的改动，必须在提交前通过测试验证。**

## 必须编写测试的场景

### 1. 数据模型变更
- 修改 `schema.ts` 中的类型定义
- 添加新的数据结构或接口
- 修改默认值配置

**要求**: 在 `schema.test.ts` 中添加对应测试用例

### 2. Store 状态管理
- 修改 `useStore.ts` 中的任何方法
- 添加新的状态管理逻辑
- 修改文件操作（增删改查）

**要求**: 在 `useStore.test.ts` 中添加对应测试用例

### 3. 核心业务逻辑
- 数据导入导出功能
- 数据迁移和兼容性处理
- localStorage 持久化逻辑
- 数据验证和规范化

**要求**: 编写独立测试文件或在现有测试中补充

### 4. 工具函数和辅助方法
- 添加新的工具函数
- 修改现有的数据处理逻辑

**要求**: 创建对应的 `*.test.ts` 文件

## 开发流程

```
1. 需求分析
   ↓
2. 编写/更新测试用例（描述预期行为）
   ↓
3. 运行测试（此时应该失败）
   ↓
4. 实现功能代码
   ↓
5. 运行测试直到全部通过
   ↓
6. 代码审查和提交
```

## 提交前检查清单

- [ ] 运行 `npm test` 确保所有测试通过
- [ ] 新增功能已添加对应测试用例
- [ ] 修改的功能已更新相关测试
- [ ] 测试覆盖了正常情况和边界情况
- [ ] 没有跳过或注释掉失败的测试

## 测试命令

```bash
# 提交前必须运行
npm test

# 开发时推荐使用监听模式
npm run test:watch

# 查看测试覆盖率
npm run test:coverage
```

## 测试编写规范

### 1. 测试文件命名
- 测试文件放在 `src/__tests__/` 目录
- 命名格式: `<源文件名>.test.ts`
- 例如: `schema.ts` → `schema.test.ts`

### 2. 测试用例结构
```typescript
describe('功能模块名称', () => {
  beforeEach(() => {
    // 每个测试前的准备工作
  })

  it('应该做某件事（正常情况）', () => {
    // 准备数据
    const input = { /* ... */ }

    // 执行操作
    const result = someFunction(input)

    // 验证结果
    expect(result).toBe(expectedValue)
  })

  it('应该处理边界情况', () => {
    // 测试空值、极端值等
  })

  it('应该处理错误情况', () => {
    // 测试异常处理
  })
})
```

### 3. 测试描述规范
- 使用中文描述，清晰表达测试意图
- 格式: "应该 + 动词 + 预期结果"
- 例如: "应该正确导入包含式神数据的文件"

### 4. Mock 使用原则
- Mock 外部依赖（Element Plus、LogicFlow 等）
- 不要 Mock 被测试的核心逻辑
- Mock 要尽可能简单和稳定

## 不需要测试的场景

以下情况可以不写单元测试：
- 纯 UI 组件的样式调整
- 简单的 getter/setter
- 第三方库的直接调用
- 临时的调试代码

但建议通过手动测试验证这些改动。

## 测试失败处理

如果测试失败：
1. **不要跳过或删除测试** - 测试失败说明代码有问题
2. 分析失败原因 - 是代码错误还是测试用例需要更新
3. 修复代码或更新测试
4. 确保所有测试通过后再提交

## 持续改进

- 定期审查测试覆盖率
- 补充缺失的测试用例
- 重构重复的测试代码
- 更新过时的测试用例