257 lines
15 KiB
Markdown
257 lines
15 KiB
Markdown
# Testing Specification
|
||
|
||
本文档定义 claude-code 项目的测试规范、当前覆盖状态和改进计划。
|
||
|
||
## 1. 技术栈
|
||
|
||
| 项 | 选型 |
|
||
|----|------|
|
||
| 测试框架 | `bun:test` |
|
||
| 断言/Mock | `bun:test` 内置 |
|
||
| 覆盖率 | `bun test --coverage` |
|
||
| CI | GitHub Actions，push/PR 到 main 自动运行 |
|
||
|
||
## 2. 测试层次
|
||
|
||
本项目采用 **单元测试 + 集成测试** 两层结构，不做 E2E 或快照测试。
|
||
|
||
- **单元测试** — 纯函数、工具类、解析器。文件就近放置于 `src/**/__tests__/`。
|
||
- **集成测试** — 多模块协作流程。集中于 `tests/integration/`。
|
||
|
||
## 3. 文件结构与命名
|
||
|
||
```
|
||
src/
|
||
├── utils/__tests__/ # 纯函数单元测试
|
||
├── tools/<Tool>/__tests__/ # Tool 单元测试
|
||
├── services/mcp/__tests__/ # MCP 单元测试
|
||
├── utils/permissions/__tests__/
|
||
├── utils/model/__tests__/
|
||
├── utils/settings/__tests__/
|
||
├── utils/shell/__tests__/
|
||
├── utils/git/__tests__/
|
||
└── __tests__/ # 顶层模块测试 (Tool.ts, tools.ts)
|
||
tests/
|
||
├── integration/ # 集成测试（尚未创建）
|
||
├── mocks/ # 共享 mock/fixture（尚未创建）
|
||
└── helpers/ # 测试辅助函数
|
||
```
|
||
|
||
- 测试文件：`<module>.test.ts`
|
||
- 命名风格：`describe("functionName")` + `test("行为描述")`，英文
|
||
- 编写原则：Arrange-Act-Assert、单一职责、独立性、边界覆盖
|
||
|
||
## 4. 当前覆盖状态
|
||
|
||
> 更新日期：2026-04-02 | **1177 tests, 64 files, 0 fail, 837ms**
|
||
|
||
### 4.1 可靠度评分
|
||
|
||
每个测试文件按断言深度、边界覆盖、mock 质量、测试独立性综合评定：
|
||
|
||
| 等级 | 含义 |
|
||
|------|------|
|
||
| **GOOD** | 断言精确（exact match），边界充分，结构清晰 |
|
||
| **ACCEPTABLE** | 正常路径覆盖完整，部分边界或断言可加强 |
|
||
| **WEAK** | 存在明显缺陷：断言过弱、重要边界缺失、或有脆弱性风险 |
|
||
|
||
### 4.2 按模块分布
|
||
|
||
#### P0 — 核心模块
|
||
|
||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||
|------|-------|------|----------|----------|
|
||
| `src/__tests__/Tool.test.ts` | 20 | GOOD | buildTool, toolMatchesName, findToolByName, filterToolProgressMessages | — |
|
||
| `src/__tests__/tools.test.ts` | 9 | ACCEPTABLE | parseToolPreset, filterToolsByDenyRules | 预设覆盖仅测 "default"；有冗余用例 |
|
||
| `src/tools/FileEditTool/__tests__/utils.test.ts` | 22 | ACCEPTABLE | normalizeQuotes, applyEditToFile, preserveQuoteStyle | `findActualString` 断言过弱（`not.toBeNull`）；`preserveQuoteStyle` 仅 2 用例 |
|
||
| `src/tools/shared/__tests__/gitOperationTracking.test.ts` | 14 | WEAK | parseGitCommitId, detectGitOperation | **未 mock analytics 依赖**，测试产生副作用；6 个 GH PR action 仅测 2 个 |
|
||
| `src/tools/BashTool/__tests__/destructiveCommandWarning.test.ts` | 21 | ACCEPTABLE | git/rm/SQL/k8s/terraform 危险模式 | safe commands 4 断言合一；缺少 `rm -rf /`、`DROP DATABASE`、管道命令 |
|
||
| `src/tools/BashTool/__tests__/commandSemantics.test.ts` | 10 | ACCEPTABLE | grep/diff/test/rg/find 退出码语义 | mock `splitCommand_DEPRECATED` 与实现可能分歧；覆盖可更全面 |
|
||
|
||
**Utils 纯函数（19 文件）：**
|
||
|
||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||
|------|-------|------|----------|----------|
|
||
| `utils/__tests__/array.test.ts` | 12 | GOOD | intersperse, count, uniq | — |
|
||
| `utils/__tests__/set.test.ts` | 11 | GOOD | difference, intersects, every, union | — |
|
||
| `utils/__tests__/xml.test.ts` | 9 | GOOD | escapeXml, escapeXmlAttr | 缺 null/undefined 输入测试 |
|
||
| `utils/__tests__/hash.test.ts` | 12 | ACCEPTABLE | djb2Hash, hashContent, hashPair | `hashContent`/`hashPair` 无已知答案断言（仅测确定性） |
|
||
| `utils/__tests__/stringUtils.test.ts` | 30 | GOOD | 10 个函数全覆盖，含 Unicode 边界 | — |
|
||
| `utils/__tests__/semver.test.ts` | 16 | ACCEPTABLE | gt/gte/lt/lte/satisfies/order | 缺 pre-release、tilde range、畸形版本串 |
|
||
| `utils/__tests__/uuid.test.ts` | 6 | ACCEPTABLE | validateUuid | 大写测试仅 `not.toBeNull`，未验证标准化输出 |
|
||
| `utils/__tests__/format.test.ts` | 20 | WEAK | formatFileSize, formatDuration, formatNumber 等 | **多处 `toContain` 应为 `toBe`**：formatNumber/formatTokens/formatRelativeTime 仅检查子串 |
|
||
| `utils/__tests__/frontmatterParser.test.ts` | 22 | GOOD | parseFrontmatter, splitPathInFrontmatter, parsePositiveIntFromFrontmatter | — |
|
||
| `utils/__tests__/file.test.ts` | 13 | ACCEPTABLE | convertLeadingTabsToSpaces, addLineNumbers, stripLineNumberPrefix | `addLineNumbers` 仅 `toContain`；缺 Windows 路径分隔符测试 |
|
||
| `utils/__tests__/glob.test.ts` | 6 | ACCEPTABLE | extractGlobBaseDirectory | 缺绝对路径、根 `/`、Windows 路径 |
|
||
| `utils/__tests__/diff.test.ts` | 8 | ACCEPTABLE | adjustHunkLineNumbers, getPatchFromContents | `getPatchFromContents` 仅检查结构，未验证 diff 内容正确性 |
|
||
| `utils/__tests__/json.test.ts` | 15 | GOOD | safeParseJSON, parseJSONL, addItemToJSONCArray | — |
|
||
| `utils/__tests__/truncate.test.ts` | 18 | ACCEPTABLE | truncateToWidth, wrapText, truncatePathMiddle | **缺 CJK/emoji/wide-char 测试**（这是宽度感知实现的核心场景） |
|
||
| `utils/__tests__/path.test.ts` | 15 | ACCEPTABLE | containsPathTraversal, normalizePathForConfigKey | 仅覆盖 2/5+ 导出函数 |
|
||
| `utils/__tests__/tokens.test.ts` | 18 | GOOD | getTokenCountFromUsage, doesMostRecentAssistantMessageExceed200k 等 | — |
|
||
|
||
**Context 构建（2 文件）：**
|
||
|
||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||
|------|-------|------|----------|----------|
|
||
| `utils/__tests__/claudemd.test.ts` | 14 | ACCEPTABLE | stripHtmlComments, isMemoryFilePath, getLargeMemoryFiles | **仅测 3 个辅助函数**，核心发现/加载/`@include` 指令/memoization 未覆盖 |
|
||
| `utils/__tests__/systemPrompt.test.ts` | 8 | GOOD | buildEffectiveSystemPrompt | — |
|
||
|
||
#### P1 — 重要模块
|
||
|
||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||
|------|-------|------|----------|----------|
|
||
| `permissions/__tests__/permissionRuleParser.test.ts` | 16 | GOOD | escape/unescape 规则，roundtrip 完整性 | — |
|
||
| `permissions/__tests__/permissions.test.ts` | 12 | ACCEPTABLE | getDenyRuleForTool, getAskRuleForTool, filterDeniedAgents | `as any` cast；缺 MCP tool deny 测试 |
|
||
| `permissions/__tests__/shellRuleMatching.test.ts` | 19 | GOOD | 通配符、转义、正则特殊字符 | — |
|
||
| `permissions/__tests__/PermissionMode.test.ts` | 18 | WEAK | permissionModeFromString, isExternalPermissionMode 等 | **`isExternalPermissionMode` false 路径从未执行**；mode 覆盖不完整（5 选 3） |
|
||
| `permissions/__tests__/dangerousPatterns.test.ts` | 7 | WEAK | CROSS_PLATFORM_CODE_EXEC, DANGEROUS_BASH_PATTERNS | 纯数据 smoke test，无行为测试；不验证数组无重复 |
|
||
| `model/__tests__/aliases.test.ts` | 15 | ACCEPTABLE | isModelAlias, isModelFamilyAlias | 缺 null/undefined/空串输入 |
|
||
| `model/__tests__/model.test.ts` | 13 | ACCEPTABLE | firstPartyNameToCanonical | 缺空串、非标准日期后缀 |
|
||
| `model/__tests__/providers.test.ts` | 9 | ACCEPTABLE | getAPIProvider, isFirstPartyAnthropicBaseUrl | `originalEnv` 声明未使用；env 恢复不完整 |
|
||
| `utils/__tests__/messages.test.ts` | 36 | GOOD | createAssistantMessage, createUserMessage, extractTag 等 16 个 describe | `normalizeMessages` 仅检查长度未验证内容 |
|
||
|
||
#### P2 — 补充模块
|
||
|
||
| 文件 | Tests | 评分 | 覆盖范围 | 主要不足 |
|
||
|------|-------|------|----------|----------|
|
||
| `utils/__tests__/cron.test.ts` | 31 | GOOD | parseCronExpression, computeNextCronRun, cronToHuman | 缺月边界、闰年 |
|
||
| `utils/__tests__/git.test.ts` | 15 | ACCEPTABLE | normalizeGitRemoteUrl (SSH/HTTPS/ssh://) | 缺 git://、file://、端口号 |
|
||
| `settings/__tests__/config.test.ts` | 38 | GOOD | SettingsSchema, type guards, validateSettingsFileContent, formatZodError | 缺 DeniedMcpServerEntrySchema |
|
||
|
||
#### P3-P6 — 扩展覆盖（27 文件）
|
||
|
||
| 文件 | Tests | 评分 | 备注 |
|
||
|------|-------|------|------|
|
||
| `utils/__tests__/errors.test.ts` | 33 | GOOD | — |
|
||
| `utils/__tests__/envUtils.test.ts` | 33 | GOOD | env 保存/恢复规范 |
|
||
| `utils/__tests__/effort.test.ts` | 30 | GOOD | 5 个 mock 模块，边界完整 |
|
||
| `utils/__tests__/argumentSubstitution.test.ts` | 22 | ACCEPTABLE | 缺转义引号、越界索引 |
|
||
| `utils/__tests__/sanitization.test.ts` | 14 | ACCEPTABLE | — |
|
||
| `utils/__tests__/sleep.test.ts` | 14 | GOOD | 时间相关测试，margin 充足 |
|
||
| `utils/__tests__/CircularBuffer.test.ts` | 11 | ACCEPTABLE | 缺 capacity=1、空 buffer getRecent |
|
||
| `utils/__tests__/memoize.test.ts` | 18 | GOOD | 缓存 hit/stale/LRU 全覆盖 |
|
||
| `utils/__tests__/tokenBudget.test.ts` | 21 | GOOD | — |
|
||
| `utils/__tests__/displayTags.test.ts` | 17 | GOOD | — |
|
||
| `utils/__tests__/taggedId.test.ts` | 10 | GOOD | — |
|
||
| `utils/__tests__/controlMessageCompat.test.ts` | 15 | GOOD | — |
|
||
| `utils/__tests__/gitConfigParser.test.ts` | 21 | GOOD | — |
|
||
| `utils/__tests__/windowsPaths.test.ts` | 19 | GOOD | 双向 round-trip 测试 |
|
||
| `utils/__tests__/envExpansion.test.ts` | 15 | GOOD | — |
|
||
| `utils/__tests__/formatBriefTimestamp.test.ts` | 10 | GOOD | 固定 now 时间戳，确定性 |
|
||
| `utils/__tests__/notebook.test.ts` | 9 | ACCEPTABLE | 合并断言偏弱 |
|
||
| `utils/__tests__/hyperlink.test.ts` | 10 | ACCEPTABLE | 空串测试行为注释混乱 |
|
||
| `utils/__tests__/zodToJsonSchema.test.ts` | 9 | WEAK | **object 属性仅 `toBeDefined` 未验证类型**；optional 字段未验证 absence |
|
||
| `utils/__tests__/objectGroupBy.test.ts` | 5 | ACCEPTABLE | 极简，缺 undefined key 测试 |
|
||
| `utils/__tests__/contentArray.test.ts` | 6 | ACCEPTABLE | 缺混合 tool_result+text 交替 |
|
||
| `utils/__tests__/slashCommandParsing.test.ts` | 8 | GOOD | — |
|
||
| `utils/__tests__/groupToolUses.test.ts` | 10 | GOOD | — |
|
||
| `utils/__tests__/shell/__tests__/outputLimits.test.ts` | 7 | ACCEPTABLE | — |
|
||
| `utils/__tests__/envValidation.test.ts` | 9 | ACCEPTABLE | **可能存在 bug**：lower bound=100 但 value=1 报 valid |
|
||
| `utils/git/__tests__/gitConfigParser.test.ts` | 20 | GOOD | — |
|
||
| `services/mcp/__tests__/mcpStringUtils.test.ts` | 16 | GOOD | — |
|
||
| `services/mcp/__tests__/normalization.test.ts` | 10 | GOOD | — |
|
||
|
||
### 4.3 评分汇总
|
||
|
||
| 等级 | 文件数 | 占比 |
|
||
|------|--------|------|
|
||
| **GOOD** | 30 | 47% |
|
||
| **ACCEPTABLE** | 26 | 41% |
|
||
| **WEAK** | 8 | 12% |
|
||
|
||
## 5. 系统性问题
|
||
|
||
### 5.1 断言过弱（Smell: `toContain` 代替精确匹配）
|
||
|
||
以下文件的部分测试使用 `toContain` 或 `not.toBeNull` 检查结果，当实现返回包含目标子串的任何字符串时测试仍通过，无法检测格式错误：
|
||
|
||
| 文件 | 受影响函数 | 建议 |
|
||
|------|-----------|------|
|
||
| `format.test.ts` | formatNumber, formatTokens, formatRelativeTime | 改为 `toBe` 精确匹配 |
|
||
| `file.test.ts` | addLineNumbers | 断言完整输出格式 |
|
||
| `diff.test.ts` | getPatchFromContents | 验证 hunk 内容正确性 |
|
||
| `notebook.test.ts` | mapNotebookCellsToToolResult | 验证合并后内容 |
|
||
| `uuid.test.ts` | validateUuid (uppercase) | 断言标准化后的精确值 |
|
||
|
||
### 5.2 集成测试空白
|
||
|
||
Spec 定义的三个集成测试均未创建：
|
||
|
||
| 计划 | 状态 | 依赖 |
|
||
|------|------|------|
|
||
| `tests/integration/tool-chain.test.ts` | 未创建 | 需 mock tools.ts 完整注册链 |
|
||
| `tests/integration/context-build.test.ts` | 未创建 | 需 mock context.ts 重依赖链 |
|
||
| `tests/integration/message-pipeline.test.ts` | 未创建 | 需 mock API 层 |
|
||
|
||
`tests/mocks/` 目录也不存在，无共享 mock/fixture 基础设施。
|
||
|
||
### 5.3 Mock 相关
|
||
|
||
| 问题 | 影响文件 | 说明 |
|
||
|------|----------|------|
|
||
| 未 mock 重依赖 | `gitOperationTracking.test.ts` | `detectGitOperation` 内部调用 analytics，测试产生副作用 |
|
||
| `isExternalPermissionMode` 永远 true | `PermissionMode.test.ts` | false 路径从未被执行，测试形同虚设 |
|
||
| env 恢复不完整 | `providers.test.ts` | 仅删除已知 key，新增 env var 会导致测试泄漏 |
|
||
|
||
### 5.4 潜在 Bug
|
||
|
||
| 文件 | 函数 | 问题 |
|
||
|------|------|------|
|
||
| `envValidation.test.ts` | validateBoundedIntEnvVar | 测试断言 lower bound=100 时 value=1 返回 `status: "valid"`，与函数名语义矛盾，可能是源码 bug 或测试逻辑错误 |
|
||
|
||
### 5.5 已知限制
|
||
|
||
| 模块 | 问题 |
|
||
|------|------|
|
||
| `Bun.JSONL.parseChunk` | 畸形行时无限挂起（Bun 1.3.10 bug） |
|
||
| `context.ts` 核心逻辑 | 依赖 bootstrap/state + git + 50+ 模块，mock 不可行 |
|
||
| `tools.ts` (getAllBaseTools) | 导入链过重 |
|
||
| `spawnMultiAgent.ts` | 50+ 依赖 |
|
||
| `messages.ts` 部分函数 | 依赖 `getFeatureValue_CACHED_MAY_BE_STALE` |
|
||
| UI 组件 (`screens/`, `components/`) | 需 Ink 渲染测试环境 |
|
||
|
||
### 5.6 Mock 模式
|
||
|
||
通过 `mock.module()` + `await import()` 解锁重依赖模块：
|
||
|
||
| 被 Mock 模块 | 解锁的测试 |
|
||
|-------------|-----------|
|
||
| `src/utils/log.ts` | json, tokens, FileEditTool/utils, permissions, memoize, PermissionMode |
|
||
| `src/services/tokenEstimation.ts` | tokens |
|
||
| `src/utils/slowOperations.ts` | tokens, permissions, memoize, PermissionMode |
|
||
| `src/utils/debug.ts` | envValidation, outputLimits |
|
||
| `src/utils/bash/commands.ts` | commandSemantics |
|
||
| `src/utils/thinking.js` | effort |
|
||
| `src/utils/settings/settings.js` | effort |
|
||
| `src/utils/auth.js` | effort |
|
||
| `src/services/analytics/growthbook.js` | effort, tokenBudget |
|
||
|
||
**约束**：`mock.module()` 必须在每个测试文件内联调用，不能从共享 helper 导入。
|
||
|
||
## 6. 改进计划
|
||
|
||
### 优先级排序
|
||
|
||
| 优先级 | 任务 | 预期效果 |
|
||
|--------|------|----------|
|
||
| **高** | 修复 8 个 WEAK 文件的断言缺陷 | 消除假阳性风险 |
|
||
| **高** | 补 `gitOperationTracking.test.ts` 的 analytics mock | 消除测试副作用 |
|
||
| **高** | 验证 `envValidation.test.ts` 潜在 bug | 排除源码缺陷 |
|
||
| **中** | 搭建 `tests/mocks/` 基础设施 | 为集成测试铺路 |
|
||
| **中** | 编写 `tests/integration/tool-chain.test.ts` | 覆盖 Tool 注册→发现→执行链路 |
|
||
| **中** | 补 `truncate.test.ts` CJK/emoji 测试 | 覆盖核心场景 |
|
||
| **低** | 补 `claudemd.test.ts` 核心逻辑 | 提升 P0 模块覆盖率 |
|
||
| **低** | 补 CLI 参数测试 (`main.tsx`) | 完成 P1 覆盖 |
|
||
| **低** | 运行 `bun test --coverage` 建立基线 | 量化覆盖率 |
|
||
|
||
### 不纳入计划
|
||
|
||
| 模块 | 原因 |
|
||
|------|------|
|
||
| `query.ts` / `QueryEngine.ts` | 核心循环，需完整集成环境 |
|
||
| `services/api/claude.ts` | 需 mock SDK 流式响应 |
|
||
| `spawnMultiAgent.ts` | 50+ 依赖 |
|
||
| `modelCost.ts` | 依赖 bootstrap/state + analytics |
|
||
| `mcp/dateTimeParser.ts` | 调用 Haiku API |
|
||
| `screens/` / `components/` | 需 Ink 渲染测试 |
|