yys-editor/src/__tests__/README.md

测试文件说明

📂 目录结构

src/__tests__/
├── setup.ts                    # 测试环境配置（ResizeObserver 等 polyfill）
├── TEST-RULES.md              # 测试规范文档（必读！）
├── README-测试报告.md          # 测试报告和问题分析
├── layer-management/          # 图层管理测试
│   ├── real-scenario.spec.ts  # ✅ 真实场景测试（推荐）
│   ├── README.md              # 图层管理测试说明
│   ├── mock-test.spec.ts.bak  # 已废弃的 Mock 测试
│   ├── integration-test.spec.ts.bak  # 已废弃的集成测试
│   └── unit-test.spec.ts.bak  # 已废弃的单元测试
├── schema.test.ts             # Schema 验证测试
└── useStore.test.ts           # Store 测试

---

🎯 测试原则

✅ 推荐：真实场景测试

优先使用真实的组件和实例，而不是 Mock 对象。

为什么？

1. 发现真实问题 - Mock 测试只能验证理想逻辑
2. 更接近用户体验 - 模拟真实的用户操作流程
3. 更可靠 - 测试通过意味着功能真的能用

示例

// ✅ 推荐：使用真实的 LogicFlow 实例
import LogicFlow from '@logicflow/core'

const lf = new LogicFlow({
  container: document.createElement('div'),
  grid: { type: 'dot', size: 10 }
})

const node = lf.addNode({ type: 'rect', x: 100, y: 100 })
lf.setElementZIndex(node.id, 'top')

// 这会发现真实问题！
const graphData = lf.getGraphRawData()
expect(graphData.nodes[0].zIndex).toBeDefined() // ❌ 失败！发现 bug

// ❌ 不推荐：使用 Mock 对象
class MockLogicFlow {
  addNode() { return { id: '1' } }
  setElementZIndex() { /* 理想逻辑 */ }
}

// 这只能验证 Mock 的逻辑，无法发现真实代码的问题

---

🚀 快速开始

运行所有测试

npm test

运行特定测试

# 运行图层管理测试
npm test -- layer-management

# 运行真实场景测试
npm test -- real-scenario

# 监听模式
npm run test:watch

# 查看详细输出
npm test -- --reporter=verbose

---

📚 文档导航

必读文档

1. TEST-RULES.md - 测试规范和最佳实践

   • 为什么要用真实场景测试
   • 如何编写好的测试
   • 何时使用 Mock

2. README-测试报告.md - 当前测试结果和问题分析

   • 发现的问题
   • 解决方案
   • 测试覆盖率

模块文档

• layer-management/README.md - 图层管理测试说明

---

📊 当前测试状态

图层管理测试

• 通过: 5/9 ✅
• 失败: 4/9 ❌

发现的问题

1. zIndex 不会保存到数据中 - 导出/导入会丢失图层信息
2. 置底操作逻辑错误 - zIndex 计算不正确

详见 README-测试报告.md

---

🔧 测试环境配置

setup.ts

提供了必要的浏览器 API polyfill：

• ResizeObserver
• IntersectionObserver
• window.matchMedia

vitest.config.js

{
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: ['./src/__tests__/setup.ts']
  }
}

---

📝 编写新测试

1. 创建测试文件

# 在对应的模块目录下创建
src/__tests__/your-module/real-scenario.spec.ts

2. 使用真实的依赖

import { describe, it, expect, beforeEach, afterEach } from 'vitest'
import LogicFlow from '@logicflow/core'

describe('你的功能测试', () => {
  let lf: LogicFlow | null = null

  beforeEach(() => {
    // 创建真实的实例
    const container = document.createElement('div')
    document.body.appendChild(container)
    lf = new LogicFlow({ container })
  })

  afterEach(() => {
    // 清理
    lf?.destroy()
  })

  it('应该能够...', () => {
    // 模拟真实的用户操作
    // 验证真实的结果
  })
})

3. 参考示例

参考 layer-management/real-scenario.spec.ts 了解如何：

• 使用真实的实例
• 模拟用户操作流程
• 提供清晰的调试信息

---

❓ 常见问题

Q: 为什么废弃 Mock 测试？

A: Mock 测试只能验证理想逻辑，无法发现真实代码的问题。例如：

• Mock 测试通过 ✅
• 但真实场景测试失败 ❌
• 发现了 zIndex 不持久化的 bug

Q: 什么时候可以使用 Mock？

A: 只在以下情况使用：

• 外部 API 调用（HTTP 请求）
• 时间相关的测试（定时器）
• 文件系统操作
• 难以复现的场景（网络错误）

详见 TEST-RULES.md

Q: 测试运行很慢怎么办？

A:

1. 使用 it.only() 运行单个测试
2. 使用 npm run test:watch 监听模式
3. 只在关键路径使用真实场景测试

---

🤝 贡献指南

添加新测试

1. 阅读 TEST-RULES.md
2. 创建测试文件
3. 使用真实的依赖
4. 模拟真实的用户操作
5. 运行测试验证

修复失败的测试

1. 查看 README-测试报告.md
2. 理解问题原因
3. 修复代码
4. 重新运行测试

---

📞 需要帮助？

• 查看 TEST-RULES.md 了解测试规范
• 查看 README-测试报告.md 了解当前问题
• 参考 layer-management/real-scenario.spec.ts 了解示例