Lesson 0007 单元测试：从 fixture 设计到安全重构

Lesson 0006 给了你可观测性——你能看到扩展的决策过程。但每次改完代码，你还是要手动跑 node out/debug.js 再人眼扫输出。本课补上缺失的另一半：自动化验证。你会学会为 getLatestTokenCount() 设计 8 种 fixture 场景，用 Node.js 内置的 node:test（零依赖）写测试，然后以测试为安全网，把 debug.ts 和 extension.ts 之间的代码复制消除为共享模块。

1. 为什么 debug.ts 不够

debug.ts 和测试解决的是两个正交的问题。一张表说清楚：

两者互补，不是替代：有测试没 debug.ts → 你知道"有 bug"但不知道"bug 在哪"。有 debug.ts 没测试 → 你能找到 bug 但你不知道"什么时候引入的"。

2. 哪些函数可以测

这个项目的核心逻辑有一个共同特征：不依赖 VS Code API。它们是纯数据变换——读 bytes、解析 JSON、计算数字、返回结构体。这意味着它们可以在任何 Node.js 进程中测试，不需要启动 VS Code：

3. Fixture 设计：用最少的数据覆盖最多的边界

Fixture（测试夹具）是人造的 .jsonl 文件，每个只包含刚好足够触发一种边界情况的数据。以下是 getLatestTokenCount() 需要覆盖的 8 种场景：

3.1 正常会话

3.2 Fixture 文件的具体内容

下面给出 4 个最关键的 fixture 的完整内容——其余 4 个在练习中自行推导：

// ===== normal-session.jsonl（3 行）=====
// 行 1：用户消息
{"type":"user","message":{"content":"Hello, can you help me write a function?"},"timestamp":"2026-06-26T10:00:00.000Z"}
// 行 2：助手回复，含 usage 和 model
{"type":"assistant","message":{"model":"claude-sonnet-4-6","usage":{"input_tokens":1500,"cache_read_input_tokens":3000,"cache_creation_input_tokens":500}},"timestamp":"2026-06-26T10:00:05.000Z"}
// 行 3：用户追问
{"type":"user","message":{"content":"Can you add error handling?"},"timestamp":"2026-06-26T10:01:00.000Z"}

// ===== clear-last.jsonl（3 行）=====
{"type":"user","message":{"content":"Analyze this code"},"timestamp":"2026-06-26T11:00:00.000Z"}
{"type":"assistant","message":{"model":"claude-sonnet-4-6","usage":{"input_tokens":800,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}},"timestamp":"2026-06-26T11:00:05.000Z"}
{"type":"user","message":{"content":"<command-name>/clear</command-name>"},"timestamp":"2026-06-26T11:05:00.000Z"}

// ===== clear-then-continue.jsonl（4 行）=====
{"type":"user","message":{"content":"First question"},"timestamp":"2026-06-26T12:00:00.000Z"}
{"type":"assistant","message":{"model":"claude-haiku-4-5","usage":{"input_tokens":300,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}},"timestamp":"2026-06-26T12:00:05.000Z"}
// ↓ /clear 结束旧会话
{"type":"user","message":{"content":"<command-name>/clear</command-name>"},"timestamp":"2026-06-26T12:10:00.000Z"}
// ↓ 新会话：/clear 之后的新消息
{"type":"user","message":{"content":"New topic: how about testing?"},"timestamp":"2026-06-26T12:15:00.000Z"}
{"type":"assistant","message":{"model":"claude-opus-4-8","usage":{"input_tokens":600,"cache_read_input_tokens":0,"cache_creation_input_tokens":100}},"timestamp":"2026-06-26T12:15:05.000Z"}

// ===== multiple-usage.jsonl（6 行，3 轮对话）=====
// 第 1 轮
{"type":"user","message":{"content":"Round 1"},"timestamp":"2026-06-26T13:00:00.000Z"}
{"type":"assistant","message":{"model":"claude-sonnet-4-6","usage":{"input_tokens":100,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}},"timestamp":"2026-06-26T13:00:05.000Z"}
// 第 2 轮
{"type":"user","message":{"content":"Round 2"},"timestamp":"2026-06-26T13:01:00.000Z"}
{"type":"assistant","message":{"model":"claude-sonnet-4-6","usage":{"input_tokens":200,"cache_read_input_tokens":0,"cache_creation_input_tokens":0}},"timestamp":"2026-06-26T13:01:05.000Z"}
// 第 3 轮
{"type":"user","message":{"content":"Round 3"},"timestamp":"2026-06-26T13:02:00.000Z"}
{"type":"assistant","message":{"model":"claude-sonnet-4-6","usage":{"input_tokens":300,"cache_read_input_tokens":50,"cache_creation_input_tokens":25}},"timestamp":"2026-06-26T13:02:05.000Z"}

3.3 测试驱动的代码审查：发现了一个潜在问题

在设计 fixture 的过程中，你会被迫逐行走读 getLatestTokenCount() 的源码——这种"为了写测试而读代码"的行为本身就能发现 bug：

// extension.ts:381 / debug.ts:111
finalUsage = {
    inputTokens: u.input_tokens || 0,
    //           ↑ 如果 JSONL 中 input_tokens 恰好是数字 0
    //             0 || 0 === 0  ✅ 没问题
    //             但如果值是 undefined → 0  ✅ 也没问题
    //             但如果值是 ""（空字符串）→ 0  ✅ 被 || 兜底
    cacheReadTokens: u.cache_read_input_tokens || 0,
    // ...
};

实际上这里用 ??（nullish coalescing）比 || 更精确——因为 0 是合法的 token 数，而 || 会把 0 和 undefined 同等对待。对数字类型，0 || 0 === 0 恰好正确——但如果 JSONL 中的 token 值意外是字符串（如 "300"），"300" || 0 返回 "300"，后续 totalTokens = "300" + 50 + 25 变成字符串拼接 "3005025"。这个 bug 在手工运行 debug.ts 时几乎不可能发现——只有测试的精确断言才会暴露它。修复方向：Number(u.input_tokens) || 0，或改用 ?? + 显式类型转换。详见第 3.2 节 multiple-usage.jsonl 的 callout。

4. 编写测试：node:test + node:assert

Node.js 18+ 内置了测试框架 node:test，零依赖——这也是本课选它的原因：纯函数 + fixture 文件场景不需要 mock，零依赖就是最优解。其他场景下（需要 mock、快照、coverage），Vitest 是社区目前最推荐的选择（详见 测试框架对比参考）。以下是测试文件的主体结构：

// ===== src/get-latest-token-count.test.ts =====
import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import * as fs from 'fs';
import * as path from 'path';

// fixture 目录：test/fixtures/
const FIXTURE_DIR = path.join(__dirname, '..', 'test', 'fixtures');
function fixture(name: string): string {
    return path.join(FIXTURE_DIR, name);
}

// 被测试的函数——从 extension.ts 复制过来
// （在提取 shared.ts 之前，先直接复制——和 debug.ts 一样的逻辑）
async function getLatestTokenCount(jsonlPath: string): Promise<TokenUsage> {
    // ... 与 extension.ts 完全相同的 90 行
}

describe('getLatestTokenCount', () => {

    it('正常会话：正确解析 usage、firstMessage、model', async () => {
        const result = await getLatestTokenCount(fixture('normal-session.jsonl'));
        assert.equal(result.totalTokens, 5000);
        assert.match(result.firstMessage || '', /Hello/);
        assert.equal(result.model, 'claude-sonnet-4-6');
        assert.equal(result.wasCleared, false);
        assert.ok(result.sessionCreated instanceof Date);
    });

    it('空文件：totalTokens=0，wasCleared=false，不抛异常', async () => {
        const result = await getLatestTokenCount(fixture('empty.jsonl'));
        assert.equal(result.totalTokens, 0);
        assert.equal(result.wasCleared, false);
        assert.equal(result.model, '');
    });

    it('/clear 结尾的会话：wasCleared=true，usage 来自 /clear 之前', async () => {
        const result = await getLatestTokenCount(fixture('clear-last.jsonl'));
        assert.equal(result.wasCleared, true);
        assert.equal(result.totalTokens, 800);
    });

    it('/clear 后有新消息：wasCleared=false，usage 来自新消息之后', async () => {
        const result = await getLatestTokenCount(fixture('clear-then-continue.jsonl'));
        assert.equal(result.wasCleared, false);
        assert.equal(result.totalTokens, 700);
        assert.equal(result.model, 'claude-opus-4-8');
    });

    it('多轮对话：totalTokens 应该是最后一轮的 usage', async () => {
        const result = await getLatestTokenCount(fixture('multiple-usage.jsonl'));
        // 第 3 轮: input_tokens="300"(→300) + cache_read=50 + cache_creation=25 = 375
        // 注意：不是第 1 轮的 100，也不是累加值 600 (=100+200+300)
        assert.equal(result.totalTokens, 375);
    });

    it('无效 JSON 行：不崩溃，跳过继续解析', async () => {
        const result = await getLatestTokenCount(fixture('malformed-lines.jsonl'));
        // 文件中有 1 行无效 JSON，应该被 catch 跳过
        assert.equal(result.totalTokens, 500);
        assert.ok(!result.wasCleared);
    });

    it('第一条消息是命令：firstMessage 应跳过命令取到下一条', async () => {
        const result = await getLatestTokenCount(fixture('command-as-first-message.jsonl'));
        // firstMessage 不应包含 <command-name>
        if (result.firstMessage) {
            assert.doesNotMatch(result.firstMessage, /command-name/);
        }
    });

    it('无 usage 记录：totalTokens=0 但 firstMessage 仍解析', async () => {
        const result = await getLatestTokenCount(fixture('no-usage.jsonl'));
        assert.equal(result.totalTokens, 0);
        assert.match(result.firstMessage || '', /./); // firstMessage 非空
    });
});

5. 超越单个函数：测试 supersession 算法

getLatestTokenCount() 只处理单个文件的解析。下一个值得测试的是同项目内多会话的淘汰逻辑——这段在 extension.ts 第 498-539 行。它与文件系统无关，是纯内存操作：

// 输入：同项目的 SessionInfo[]（已按 sessionCreated 从新到老排列）
const input: SessionInfo[] = [
    { sessionId: 'new',  sessionCreated: new Date('2026-06-27'), lastUpdated: new Date('2026-06-27'), wasCleared: false },
    { sessionId: 'old-a', sessionCreated: new Date('2026-06-25'), lastUpdated: new Date('2026-06-26'), wasCleared: false },
    { sessionId: 'old-b', sessionCreated: new Date('2026-06-24'), lastUpdated: new Date('2026-06-27'), wasCleared: false },
];

// 期望输出：
//   'new'  ✅ SHOW（最新的，没有更新的覆盖它）
//   'old-a' ❌ HIDE（new.created=6/27 > old-a.lastUpdated=6/26 → 被取代）
//   'old-b' ✅ SHOW（new.created=6/27 不大于 old-b.lastUpdated=6/27，且 old-b.created=6/24 不大于 old-a.lastUpdated=6/26 → 未被取代）

这个测试不依赖任何文件系统——你直接构造 SessionInfo[] 数组，调用淘汰逻辑，断言结果。它的价值在于：它把 Lesson 0004 第 6 节的文字描述变成了可执行的断言。

6. 以测试为安全网，提取 shared.ts

Lesson 0006 第 2 节讨论了"为什么不提取共享模块"——核心理由是 ~150 行复制比引入一个新模块边界更简单。这个判断在没有测试时是对的。但有了测试之后，方程变了：

具体步骤：

# 步骤 1：写测试（覆盖 getLatestTokenCount 的所有边界）
node --test out/get-latest-token-count.test.js   # 8 tests pass ✅

# 步骤 2：提取 shared.ts——把两个文件中的同名函数替换为 import
#   shared.ts  ← 移入 getLatestTokenCount() + TokenUsage + SessionInfo
#   extension.ts → import { getLatestTokenCount } from './shared'
#   debug.ts     → import { getLatestTokenCount } from './shared'

# 步骤 3：再跑一次测试——如果全绿，提取成功
node --test out/get-latest-token-count.test.js   # 8 tests still pass ✅

# 步骤 4：删除两个文件中复制的 90 行——代码去重完成

7. 练习

1. 在 temp_repo/test/fixtures/ 目录下创建 normal-session.jsonl、empty.jsonl 和 clear-last.jsonl，内容参考第 3.2 节。不要求格式完美——重点是体验"最少数据触发最多边界"的 fixture 设计思维
2. 把这 3 个 fixture 文件复制到 temp_repo/out/ 旁边，写一个最小测试文件 temp_repo/src/minimal.test.ts，只测"正常会话"这一个场景。用 npx tsx --test src/minimal.test.ts 运行——确认你能跑通一个测试再继续
3. 完成 8 种场景的全部 fixture 文件——剩余 5 种（clear-then-continue、no-usage、multiple-usage、malformed-lines、command-as-first-message）根据 3.1 节的描述自行构造。每个文件 ≤ 10 行
4. （进阶）提取 supersession 淘汰逻辑为独立函数，为它写测试——构造 3 个 SessionInfo 对象，覆盖"新会话取代老会话""老会话未被取代""wasCleared 直接淘汰"三种情况。详见第 5 节
5. （进阶）在全部测试通过后，尝试提取 shared.ts——把 getLatestTokenCount() 和两个 interface 移到新文件，让 extension.ts 和 debug.ts 都 import 它。跑测试确认没有引入回归。感受"测试驱动重构"的工作流
6. （思考）你写完测试后，如果发现某个 fixture 的断言结果和预期不同——是代码有 bug，还是你的理解有误？记录这个判断过程。这是测试最重要的副产品：它让你直面"我以为的行为"和"实际的行为"之间的差距

8. 知识检查

9. 推荐深入阅读

• Node.js：node:test 官方文档 — describe/it、assert、mock、coverage 的完整参考
• Node.js：node:assert/strict 官方文档 — 严格模式的断言方法（equal、deepEqual、match、throws 等）
• tsx — 零配置的 TypeScript 执行器，让 node --test 直接跑 .ts 文件
• Lesson 0006：debug.ts — 本课的直接前置：可观测性 vs 可验证性
• Lesson 0004：findActiveSessions — 本课测试的核心函数来源
• Martin Fowler：TestCoverage — 测试覆盖率应该多高？Fowler 论证了"覆盖率不是目的，而是诊断工具"
• 📖 测试框架对比参考 — node:test vs Jest vs Vitest vs Mocha 完整对比、选型建议、API 速查