Rust / 系统课时

按模块组织测试代码

按模块组织测试代码

Rust 测试代码放在哪里,会直接影响它能访问哪些项目内部细节。理解模块边界、可见性与测试位置后,你可以把真正需要内部访问的测试留在单元测试中,同时避免为了测试方便而随意扩大生产代码的公开接口。

学习目标

  • 理解测试模块与生产代码模块之间的可见性关系
  • 能选择合适的位置组织单元测试
  • 能用最小示例验证私有函数是否可以被单元测试直接访问

测试位置决定访问边界

Rust 的单元测试通常直接写在被测模块附近,并放入 #[cfg(test)] mod tests。这种组织方式的一个重要特点是:测试模块可以使用父模块中的私有项,因此适合验证内部实现规则。

例如,一个库模块有私有函数 normalize_name,可以把测试紧邻实现放在同一个文件中:

rust
pub mod user {
    fn normalize_name(name: &str) -> String {
        name.trim().to_lowercase()
    }

    pub fn display_name(name: &str) -> String {
        normalize_name(name)
    }

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

        #[test]
        fn normalizes_internal_name() {
            // 单元测试直接检查模块内部规则。
            assert_eq!(normalize_name("  Alice "), "alice");
        }

        #[test]
        fn checks_public_behavior() {
            assert_eq!(display_name("  Alice "), "alice");
        }
    }
}

预期结果

text
running 2 tests
test user::tests::checks_public_behavior ... ok
test user::tests::normalizes_internal_name ... ok

test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

这里 tests 本身也是一个模块,use super::* 把父模块中的项目引入测试作用域。测试函数因此可以直接访问私有的 normalize_name。这并不意味着私有函数对整个 crate 或外部调用者变成了公开 API。

什么测试适合放在模块内部

模块内部测试适合验证聚焦于当前模块的规则,例如输入规范化、边界判断、状态转换或内部辅助函数。它们可以针对实现细节,因此定位代码问题通常更直接。

但不要因为测试需要访问私有项,就把所有测试都塞进同一个模块。测试仍然应该围绕模块职责组织,让失败信息能够回答“哪个模块的规则坏了”。一个大型模块可以继续拆出多个内部测试模块,但应保持测试名称能表达业务行为。

用可见性区分测试目标

可以把两类测试简单区分为“验证内部规则”和“验证对外行为”。前者依赖模块内部结构,后者更强调公开接口是否满足约定。

测试目标 常见位置 主要关注点
内部规则 被测模块的 #[cfg(test)] 模块 私有函数、内部状态、实现规则
对外行为 同一单元测试模块或独立集成测试 公开 API、用户可观察结果

如果一个测试只有在访问私有变量或私有函数时才成立,它通常更适合靠近被测模块。若测试只需要调用公开 API,就应尽量避免依赖内部实现细节,这样重构时不容易大面积改测试。

组织代码时避免过度暴露

一个常见错误是:为了让外部测试访问内部函数,直接把原本私有的函数改成 pub。这会扩大 API 表面,而且测试需求不应该反过来决定生产代码的可见性。

更稳妥的方式是先判断测试真正要验证什么。如果目标是内部规则,就让单元测试留在模块内部;如果目标是公开契约,再通过公开入口验证。这样“测试放哪里”和“代码应该公开到什么程度”是两个独立的设计决定。

用 cargo test 验证组织结果

保存代码后,在项目根目录运行:

bash
cargo test

预期结果

text
测试模块被自动发现并执行;本示例中的 2 个测试均通过,最终结果包含 2 passed 和 0 failed。

当项目继续变大时,优先按模块职责组织单元测试,再决定哪些行为值得通过公开 API 做更高层验证。这样既能保留对内部规则的精确检查,也能让生产代码的可见性保持在真正需要的范围内。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

按模块组织测试代码

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通