添加测试套件

[cunoe]

问题描述

项目目前没有任何自动化测试，test 脚本是 placeholder。

期望行为

• 引入测试框架（推荐 vitest）
• 覆盖核心模块：config parser/validator、db operations、url parsing、env utils
• CI 中运行测试

[leaperone-bot]

🤖 Leo 自动分析

现在我已经对整个代码库有了全面的了解。以下是我的技术分析：

---

技术分析：Issue #20 — 添加测试套件

📋 问题定义

Issue 描述清晰、可操作。项目当前零测试覆盖，package.json 中 test 脚本为占位符 (echo "Error: no test specified" && exit 1)，CI 流水线中也没有测试步骤。

---

🎯 范围评估

需要覆盖 5 个核心模块，按测试优先级排列：

模块	文件	可测性	优先级
URL 解析	src/utils/url.ts	⭐⭐⭐ 纯函数，无副作用	P0
Env 工具	src/utils/env/index.ts	⭐⭐⭐ 大部分为纯函数	P0
Config Parser	src/utils/config/config-parser.ts	⭐⭐⭐ 静态方法，易测	P0
Config Validator	src/utils/config/config-validator.ts	⭐⭐⭐ 纯逻辑校验	P0
DB 操作	src/utils/db.ts	⭐⭐ 需要真实 SQLite	P1
Config Manager	src/utils/config/config-manager.ts	⭐⭐ 有文件 I/O 依赖	P1
公共操作	src/utils/com.ts	⭐ 组合层，集成测试	P2

---

🛠️ 建议实现方案

1. 测试框架选型：Vitest

理由充分：

• 项目已使用 ESM + TypeScript + tsup，Vitest 原生支持 ESM，无需额外配置
• 与项目已有的 tsconfig.json 配置（paths 别名 @/*）兼容良好
• 内置覆盖率报告（c8/istanbul），无需额外依赖
• Issue 中明确推荐 vitest

2. 安装与配置

pnpm add -D vitest @vitest/coverage-v8

需要创建 vitest.config.ts，关键配置：

• resolve.alias：映射 @/* → src/*（与 tsconfig paths 一致）
• test.include：['src/**/*.test.ts'] 或 ['tests/**/*.test.ts']
• test.environment：node

修改 package.json：

"test": "vitest run",
"test:watch": "vitest",
"test:coverage": "vitest run --coverage"

3. 各模块测试策略

URL 解析 (url.ts) — 约 15-20 个测试用例：

• parseRef(): 完整 URL、相对格式 ns/proj:tag、仅 tag、环境变量回退、缺失字段抛错
• buildPushUrl() / buildPullUrl(): URL 拼接、末尾斜杠处理
• validateUrl(): 合法/非法 URL
• normalizeBaseUrl(): http/https 补全

Env 工具 (env/index.ts) — 约 20-25 个测试用例：

• parseEnv(): 基础解析、注释跳过、引号处理（单/双）、空行、无等号行
• serializeEnv(): 序列化格式、双引号转义
• mergeEnv(): 普通合并、force 模式、undefined 值处理
• validateEnvKey(): 合法/非法键名（数字开头、特殊字符）
• generateExportCommand() / generateUnsetCommand(): 各 shell 类型（bash/zsh/fish/cmd/powershell）
• readEnvFile() / writeEnvFile(): 需要临时文件（vitest 的 beforeEach/afterEach 管理）

Config Parser (config-parser.ts) — 约 15 个测试用例：

• parseFromString(): 合法 YAML、非法 YAML、缺失字段
• validateConfig(): version 校验、env 结构校验、target 格式警告
• normalizeEnvValue(): null/undefined/string/object 各种输入
• getEnvConfigs(): 遍历提取

Config Validator (config-validator.ts) — 约 20 个测试用例：

• validateFull(): 综合场景
• isValidEnvKey(): 正则边界（_KEY、123KEY、KEY-NAME、含空格）
• isValidPath(): 相对路径 ./、绝对路径 /、Windows 路径 C:、波浪号 ~
• isValidTarget(): @user/proj、@user/proj/key、local、<url>、非法格式
• hasCircularReference(): 简单循环、无循环（注意：当前实现是空操作，此处应添加 TODO）
• getConfigSummary(): 统计准确性

DB 操作 (db.ts) — 约 15 个测试用例：

• 使用临时目录创建测试数据库（os.tmpdir() + 随机目录）
• batchUpsertTaggedValues(): 插入、更新（upsert）、自动 tag 生成
• getTaggedValues(): 查询已存在/不存在的 tag
• getHistoryByKey() / getAllHistory(): 数据查询与 limit
• getAllTags() / getStats() / getTagStats(): 统计信息
• 每个测试后调用 close() 并清理临时文件

4. CI 集成

修改 .github/workflows/publish.yml，在 test job 中添加：

- run: pnpm test

放在 pnpm lint 和 pnpm build 之间。

---

⚠️ 风险和注意事项

1. 路径别名 @/*：tsconfig.json 中配置了 "@/*": ["*"]（基于 src/），Vitest 需要在 vitest.config.ts 中配置对应的 resolve.alias，否则测试中的 import 会失败。

2. better-sqlite3 原生模块：这是一个 C++ 原生 Node addon。在 CI 的 ubuntu-latest 上需要确保编译工具链可用（通常默认有），但如果后续加 matrix 测试（如 Windows），可能需要注意。

3. 文件 I/O 测试隔离：ConfigManager、readEnvFile、writeEnvFile 等涉及文件系统操作，需要使用临时目录来隔离，避免测试间相互影响。

4. process.env 污染：parseRef() 和 detectDefaultShell() 读取 process.env，测试中需要保存/恢复环境变量，或使用 vi.stubEnv() / vi.unstubAllEnvs()。

5. hasCircularReference() 当前为空实现：该方法内部只检查了 visited set 但实际没有递归追踪 target 引用。测试时会发现这个逻辑空洞——这是一个潜在 Bug，建议作为发现项单独记录。

6. ESM 兼容性：项目使用 "type": "module"，Vitest 原生支持 ESM，但需注意 better-sqlite3 是 CommonJS 模块，可能需要在 Vitest 配置中的 deps.interopDefault 做处理。

---

📊 复杂度评估

中等（Medium）

• 工作量约 2-3 天
• 约 80-100 个测试用例
• 新增文件：1 个配置文件 + 5-7 个测试文件
• 修改文件：package.json（依赖 + 脚本）、.github/workflows/publish.yml（CI 步骤）
• 无需修改业务代码（除非测试中发现 Bug）

📁 建议的测试文件结构

src/
├── utils/
│   ├── __tests__/          # 或 tests/ 在项目根目录
│   │   ├── url.test.ts
│   │   ├── env.test.ts
│   │   ├── db.test.ts
│   │   ├── config-parser.test.ts
│   │   ├── config-validator.test.ts
│   │   └── config-manager.test.ts
vitest.config.ts

---

✅ 总结

此 Issue 目标明确、范围合理。项目的核心工具模块（url/env/config/db）大多为纯函数或静态方法，可测性很好。推荐使用 Vitest，优先覆盖纯逻辑模块（url、env、config-parser、config-validator），其次覆盖有 I/O 依赖的模块（db、config-manager）。CI 集成只需在现有 workflow 中加一行 pnpm test。