Test Coverage Report: [Concept Name]

Concept Page: /docs/concepts/[slug].mdx Test File: /tests/{category}/{concept}/{concept}.test.js DOM Test File: /tests/{category}/{concept}/{concept}.dom.test.js (if applicable)

Summary

Metric	Count
Total Code Examples in Doc	XX
Testable Examples	XX
Tests Written	XX
DOM Tests Written	XX
Skipped (with reason)	XX

Tests by Section

Section	Line Range	Examples	Tests	Status
[Section 1]	XX-YY	X	X	PASS

Skipped Examples

Line	Example Description	Reason
XX	ASCII diagram of call stack	Conceptual, not executable

报告的价值在于把"示例总数 = 已测数 + 已解释跳过数"变成可核对的等式——任何一条没被覆盖也没被解释的示例都会显形。

## 10. 质量检查清单与常见问题

### 10.1 四维质量清单

SKILL 的质量检查分四个维度，可作为 PR 自检：

**完整性**
- 所有可测试示例都有对应测试
- 测试按文档章节组织
- 注释中包含源行号引用（From lines XX-YY）
- DOM 测试位于独立的 `.dom.test.js` 文件
- 边界情况与错误示例均已覆盖

**正确性**
- 测试验证的是文档实际描述的行为
- 文档中的输出注释与测试期望一致
- 异步测试正确使用了 async/await
- 错误测试使用了正确的 `toThrow` 模式
- 浮点数比较使用 `toBeCloseTo`
- 对象比较使用 `toEqual`（而非 `toBe`）

**约定**
- 显式从 vitest 导入
- 遵循 describe/it 嵌套模式
- 测试名以 "should" 开头
- 文件命名符合 `{concept}.test.js`
- DOM 测试带有 jsdom 环境声明

**验证**
- `npm test -- tests/{category}/{concept}/` 全部通过
- 没有无理由跳过的测试
- 没有假阳性（因错误原因而通过的测试）

### 10.2 四类常见故障

**故障一：测试通过但断言方式错误。** 文档写 `console.log(result) // [1, 2, 3]`，若用 `toBe([1, 2, 3])` 则因引用不等而失败或误导，必须用 `toEqual([1, 2, 3])`。

**故障二：异步测试超时。** 根因是未 await，修复方式是给 `it` 回调加 `async` 并对 Promise 结果 await：

```javascript
// Bad —— 缺少 await，断言的是 Promise 而非结果
it('should fetch data', () => {
  const data = fetchData()
  expect(data).toBeDefined()
})

// Good
it('should fetch data', async () => {
  const data = await fetchData()
  expect(data).toBeDefined()
})

故障三：DOM 测试报 "document is not defined"。 根因是缺少 jsdom 环境声明，在文件顶部添加 /** @vitest-environment jsdom */ 即解决。

故障四：测试间相互污染。 前一个用例修改了 document.body 或遗留 mock，导致后一个用例结果漂移。标准解法：

afterEach(() => {
  document.body.innerHTML = ''
  vi.restoreAllMocks()
})