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) Date: YYYY-MM-DD Author: [Name/Claude]

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	✅
[Section 2]	XX-YY	X	X	✅
[Section 3]	XX-YY	X	X	⚠️ (1 skipped)

Skipped Examples

Line	Example Description	Reason
XX	ASCII diagram of call stack	Conceptual, not executable
YY	Browser fetch example	Requires network, mocked instead

Test Execution

npm test -- tests/{category}/{concept}/

Result: ✅ XX passing | ❌ X failing | ⏭️ X skipped

Notes

[Any special considerations, mock requirements, or issues encountered]

报告模板中"Concept Page 使用 `/docs/concepts/[slug].mdx`、Test File 使用 `/tests/{category}/{concept}/`"的路径约定，与仓库实际的 `docs/concepts/` + 分层 `tests/` 结构完全一致；Skipped Examples 表则强制落实 Phase 1 中"跳过必须记录原因"的要求。

## 十、常见问题与排查

### 问题 1：测试通过了，但本不该通过

**现象**：期望值与文档输出不匹配，断言"碰巧"成立。
**排查**：逐一核对期望值是否与 `console.log` 输出注释**完全一致**。

```javascript
// Documentation says: console.log(result)  // [1, 2, 3]
// Make sure test uses:
expect(result).toEqual([1, 2, 3])  // NOT toBe for arrays
```

数组/对象断言误用 `toBe` 是典型错误：`toBe` 比较引用，两个内容相同的数组并非同一对象，会导致断言失败或语义错误。

### 问题 2：异步测试超时

**现象**：异步测试永不 resolve。
**排查**：确保所有 Promise 被 await，且 `it` 回调声明为 `async`。

```javascript
// Bad
it('should fetch data', () => {
  const data = fetchData()  // Missing await!
  expect(data).toBeDefined()
})

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

Bad 用例中 `data` 是一个 Promise，`toBeDefined()` 对任何 Promise 都为真——这正是质量清单里"假阳性"检查项要防范的情形。

### 问题 3：DOM 测试报 "document is not defined"

**现象**：默认 Node 环境中没有 `document`。
**排查**：在文件顶部添加环境指令：

```javascript
/**
 * @vitest-environment jsdom
 */
```

这与 [vitest.config.js](https://gitcode.com/GitHub_Trending/33/33-js-concepts/blob/60f9337d5e7a6dbc4f74dffc9c1a4c818652b4a7/vitest.config.js?utm_source=gitcode_repo_files) 中 `environment: 'node'` 的全局默认值互为补充：全局 Node、单文件 jsdom，按文件粒度切换。

### 问题 4：测试之间相互影响

**现象**：某个用例单独运行通过、全量运行失败。
**排查**：为 DOM 与 mock 建立清理边界：

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