RTK 测试模式详解：未测模块 Backlog 与 RTK 项目四大核心 Rust 测试模式

本文以 RTK 仓库中 rtk-tdd 技能自带的参考文档 testing-patterns.md 为核心，系统讲解该文档定义的未测模块优先级 Backlog、四类 RTK 专属测试模式（过滤函数、纯计算、验证/安全、ANSI 剥离）以及可直接套用的测试骨架模板。读完后，你将能够按 Backlog 挑出最值得补测试的模块、为不同代码类型选择正确的断言策略，并结合 源码 中的真实实现理解每种模式为什么这样写。

参考文档的定位：rtk-tdd 技能的执行手册

RTK 是一个用单个 Rust 二进制实现的 CLI 代理，其核心工作是把 git、cargo、npm 等常见开发命令的输出压缩 60%～90%，以降低 LLM 的 token 消耗。为了让 AI Agent 和人类贡献者在给 RTK 写代码时强制走 TDD，仓库在 .claude/skills/rtk-tdd/SKILL.md 中定义了技能入口，而本文聚焦的 testing-patterns.md 则是该技能的参考文档，回答三个落地问题：先测什么（Backlog）、用什么模式（Pattern）、怎么组织代码（Skeleton）。

SKILL.md 中定义的 Red-Green-Refactor 循环是这些测试模式的执行框架：

1. 在同一个文件的 #[cfg(test)] mod tests 中写测试；
2. cargo test MODULE::tests::test_name —— 必须先失败（Red）；
3. 写最小实现；
4. 重跑测试必须通过（Green）；
5. 重构，再跑测试保持 Green；
6. 最终门禁：cargo fmt && cargo clippy --all-targets && cargo test。

其中第 2 步不可跳过——“如果测试立即通过，说明它什么都没测”。testing-patterns.md 的价值就在于：当你在第 1 步写测试时，它告诉你 RTK 代码库中每一类代码对应的标准写法。

未测模块 Backlog：按可测性排优先级

参考文档开篇给出的 Backlog 原则是“Prioritized by testability (pure functions first, I/O-heavy last)”——纯函数优先，重 I/O 最后。这是 RTK 这类“输出过滤器型”CLI 工具最务实的策略：过滤函数天然是 str -> str，不需要 mock 进程、不需要文件系统。

高优先级（纯函数，极易测试）

模块	可测函数	备注
diff_cmd.rs	compute_diff、similarity、truncate、condense_unified_diff	4 个纯函数，0 测试
env_cmd.rs	mask_value、is_lang_var、is_cloud_var、is_tool_var、is_interesting_var	5 个分类函数

从源码结构看，这份清单与现状吻合：

• src/cmds/git/diff_cmd.rs 中确实存在 compute_diff（L262）、similarity（L308）、condense_unified_diff（L322）三个私有纯函数，输入输出都是切片或字符串，无 I/O 依赖；
• src/cmds/system/env_cmd.rs 中可确认 is_lang_var（L132）、is_cloud_var（L140）、is_tool_var（L158）、is_interesting_var（L176）四个分类判定函数；mask_value 为文档 Backlog 所列，当前源码中未见同名函数，跟随清单时建议以实际函数名为准。

这类函数是 TDD 的理想对象：给定环境变量名列表，断言每个键被分进正确类别即可，断言成本极低。

中优先级（需要 tempfile 或构造解析输入）

模块	可测函数	备注
tracking.rs	estimate_tokens、Tracker::new、query 方法	SQLite 用 tempfile
config.rs	Config::default、配置解析	测默认值和 TOML 解析
deps.rs	依赖文件解析	用示例 Cargo.toml / package.json 字符串测试
summary.rs	输出类型检测启发式	纯字符串分析

其中 estimate_tokens 可在 src/core/tracking.rs 中确认，是 RTK 统计“节省了哪些 token”的核心估算入口；由于 Tracker 会落 SQLite 数据库，文档建议用 tempfile 创建临时数据库来隔离文件系统副作用，这与 SKILL.md 的“Direct I/O (SQLite, network) -> use tempfile/mock”原则一致。config.rs 和 deps.rs 的测试要点则分别是“默认值断言 + TOML 解析”和“喂入示例 Cargo.toml/package.json 字符串”，都是把 I/O 边界替换成内存字符串的典型手法。

低优先级（重 I/O、CLI 接线）

模块	可测函数	备注
container.rs	Docker/kubectl 输出过滤器	需要 mock Command 输出
find_cmd.rs	目录分组逻辑	依赖文件系统
wget_cmd.rs	compact_url、format_size、truncate_line、extract_filename_from_output	部分纯 helper 值得测
gain.rs	展示格式化	依赖 tracking DB
init.rs	CLAUDE.md 生成	文件 I/O
main.rs	CLI 路由	由 smoke 测试覆盖

即便在这一档里，文档也点出了“值得测的纯 helper”：例如 src/cmds/cloud/wget_cmd.rs 中的 truncate_line（L254）就是无状态字符串处理，可以脱离 wget 进程单独断言；同理 src/cmds/git/git.rs 中也有一个 truncate_line（L789）供 git 输出裁剪使用。原则是：只测解析/裁剪逻辑，不测子进程执行本身——调用 Command::new() 的部分应交给集成/冒烟测试覆盖。

四大 RTK 测试模式

参考文档中段给出四种模式，覆盖 RTK 代码库中几乎全部被测代码的形状。以下逐一给出文档原样代码、实际使用位置和源码级原理。

模式 1：Filter Function（RTK 中最常见）

#[test]
fn test_FILTER_happy_path() {
    // Arrange: raw command output as string literal
    let input = r#"
line of noise
line with relevant data
more noise
"#;
    // Act
    let result = filter_COMMAND(input);
    // Assert: output contains expected, excludes noise
    assert!(result.contains("relevant data"));
    assert!(!result.contains("noise"));
}

关键技巧是用原始字符串字面量 r#"..."# 内嵌一段真实命令输出作为输入，然后做一对正/负断言：结果必须 contains 关键信息，且必须不 contains 噪声。这正是 RTK 的产品契约——压缩后的输出不能丢语义、必须去噪。文档列出该模式的使用模块：git.rs、grep_cmd.rs、lint_cmd.rs、tsc_cmd.rs、vitest_cmd.rs、pnpm_cmd.rs、next_cmd.rs、prettier_cmd.rs、playwright_cmd.rs、prisma_cmd.rs，基本覆盖了 src/cmds/ 下各语言工具链的过滤器。

写这类测试时，输入样本最好取自真实命令输出（仓库的 tests/fixtures/ 目录中保存了大量 mvn_*_raw.txt、sbt_*、gradlew_*_raw.txt 等原始输出快照，可作为 Arrange 阶段的现成素材，参考 tests/grep_faithful_format_test.rs 等测试的组织方式）。

模式 2：Pure Computation

#[test]
fn test_FUNCTION_deterministic() {
    assert_eq!(truncate("hello world", 8), "hello...");
    assert_eq!(truncate("short", 10), "short");
}

以 truncate 为例，其真实实现在 src/core/utils.rs：

pub fn truncate(s: &str, max_len: usize) -> String {
    let char_count = s.chars().count();
    if char_count <= max_len {
        s.to_string()
    } else if max_len < 3 {
        // If max_len is too small, just return "..."
        "...".to_string()
    } else {
        format!("{}...", s.chars().take(max_len - 3).collect::<String>())
    }
}

从实现看，测试断言的两个用例恰好命中三条分支："hello world"（11 字符）超过 8，走 take(max_len - 3) 分支得到 "hello..."；"short" 未超限原样返回。写纯函数测试时值得照此把边界分支（恰等于、max_len < 3 的退化情况、Unicode 多字节字符）都各写一条 assert_eq!。该模式文档列出的使用位置：gh_cmd.rs 的 truncate，以及 src/core/utils.rs 中的 truncate、format_tokens、format_usd——后两个是 token/金额格式化函数，同样是确定性输出，适合精确相等断言。

模式 3：Validation / Security

#[test]
fn test_VALIDATOR_rejects_injection() {
    assert!(!is_valid("malicious; rm -rf /"));
    assert!(!is_valid("../../../etc/passwd"));
}

验证类函数是布尔输出，测试策略是喂入恶意边界输入并断言被拒绝：命令注入载荷（; rm -rf /）、路径穿越（../../../etc/passwd）都必须返回假。文档给出的用例是 pnpm_cmd.rs 中的 is_valid_package_name（按文档所列；当前源码中该函数名未见同名定义，以实际命名为准），位于 src/cmds/js/pnpm_cmd.rs。对 RTK 这类“代理用户命令”的 CLI 工具，这类校验直接关系到不会把恶意包名/路径拼进子进程参数，是安全回归测试的核心位置。

模式 4：ANSI Stripping

#[test]
fn test_strip_ansi() {
    let input = "\x1b[32mgreen\x1b[0m normal";
    let output = strip_ansi(input);
    assert_eq!(output, "green normal");
    assert!(!output.contains("\x1b["));
}

大量开发工具（测试框架、lint 器）在终端输出里带 ANSI 颜色转义，如果 RTK 的过滤器直接处理带色输出，匹配和压缩逻辑都会失效，因此剥离转义码是预处理必测项。实现见 src/core/utils.rs：

pub fn strip_ansi(text: &str) -> String {
    static ANSI_RE: LazyLock<Regex> =
        LazyLock::new(|| Regex::new(r"\x1b\[[0-9;]*[a-zA-Z]").unwrap());

    ANSI_RE.replace_all(text, "").to_string();
}

正则 \x1b\[[0-9;]*[a-zA-Z] 匹配 CSI 序列（ESC + [ + 数字/分号参数 + 终止字母），文档示例中的 \x1b[32m（绿色）和 \x1b[0m（重置）都会被清除，得到 "green normal"，与实现行为一致。文档列出的使用位置：vitest_cmd.rs 与 utils.rs；此外 src/cmds/php/utils.rs 中还有一个 strip_ansi_and_controls，在剥离 ANSI 的同时清理控制字符，属于同一模式的变体。

测试骨架模板：可直接复制的结构

参考文档最后给出标准骨架，把前四种模式统一成一套结构：

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_FUNCTION_happy_path() {
        // Arrange
        let input = r#"..."#;
        // Act
        let result = FUNCTION(input);
        // Assert
        assert!(result.contains("expected"));
        assert!(!result.contains("noise"));
    }

    #[test]
    fn test_FUNCTION_empty_input() {
        let result = FUNCTION("");
        assert!(...);
    }

    #[test]
    fn test_FUNCTION_edge_case() {
        // Boundary conditions: very long input, special chars, unicode
    }
}

模板要点：

• 位置：测试与实现同文件（SKILL.md 明确要求写在同一文件的 #[cfg(test)] mod tests 中），运行命令形如 cargo test diff_cmd::tests::test_compute_diff_happy_path；
• 命名规范：test_{function}_{scenario} 或 test_{function}_{input_type}，例如 test_truncate_edge_case、test_parse_invalid_input、test_filter_empty_string；
• 三类场景齐全：happy path（正常输入）、empty input（空串是 CLI 过滤器最常见的崩溃点）、edge case（超长输入、特殊字符、Unicode 多字节边界——对 truncate 这类按 chars() 计数的函数尤其必要）；
• 断言策略按模式选择：过滤类用 contains/!contains，纯计算用 assert_eq! 精确比对，验证类用布尔断言，错误路径用 assert!(result.is_err())。

何时不用纯 TDD，以及提交前门禁

Backlog 把重 I/O 模块排到最低，背后是 SKILL.md 明确列出的例外原则，补测试时同样适用：

• 调用 Command::new() 的函数：测其解析/过滤逻辑，不测子进程执行；
• 含 std::process::exit() 的函数：先重构成返回 Result，再对 Result 做测试；
• 直接 I/O（SQLite、网络）：用 tempfile::NamedTempFile 或 mock，或把纯逻辑拆出来单独测；
• main.rs 这类 CLI 路由接线：由集成/冒烟测试覆盖，不写单元测试。

对应地，Backlog 中“中优先级”模块（tracking.rs 用 tempfile、deps.rs 用示例字符串）和低优先级模块（container.rs 需 mock Command 输出）的备注，正是这些原则的逐模块落点。完成一个函数/模块的测试后，SKILL.md 定义的提交前门禁三条必须全部通过：

cargo fmt --all --check
cargo clippy --all-targets
cargo test

实践路径小结

把参考文档用起来的最短路径：

1. 从高优先级 Backlog 挑一个 0 测试的纯函数组，例如 diff_cmd.rs 的 compute_diff / similarity / condense_unified_diff；
2. 判定代码类型——这里属于模式 2（纯计算），若函数是输出过滤器则属模式 1；
3. 按骨架模板在同文件写 happy / empty / edge 三个 #[test]，先跑红（无实现或故意失败），再补最小实现跑绿；
4. 以 cargo fmt && cargo clippy --all-targets && cargo test 作为最终门禁，然后处理 Backlog 中的下一项。

这套“Backlog 排优先级 + 模式对号入座 + 统一骨架”的组合，让给 RTK 这类输出压缩型 CLI 工具补测试变成了高度机械化的流程：测试的输入是命令输出快照，断言的是压缩后输出的保真与去噪，恰好覆盖了这个项目最核心的质量契约。