Rust / 系统课时
按模块组织测试代码
按模块组织测试代码
Rust 测试代码放在哪里,会直接影响它能访问哪些项目内部细节。理解模块边界、可见性与测试位置后,你可以把真正需要内部访问的测试留在单元测试中,同时避免为了测试方便而随意扩大生产代码的公开接口。
学习目标
- 理解测试模块与生产代码模块之间的可见性关系
- 能选择合适的位置组织单元测试
- 能用最小示例验证私有函数是否可以被单元测试直接访问
测试位置决定访问边界
Rust 的单元测试通常直接写在被测模块附近,并放入 #[cfg(test)] mod tests。这种组织方式的一个重要特点是:测试模块可以使用父模块中的私有项,因此适合验证内部实现规则。
例如,一个库模块有私有函数 normalize_name,可以把测试紧邻实现放在同一个文件中:
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");
}
}
}预期结果
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 验证组织结果
保存代码后,在项目根目录运行:
cargo test预期结果
测试模块被自动发现并执行;本示例中的 2 个测试均通过,最终结果包含 2 passed 和 0 failed。当项目继续变大时,优先按模块职责组织单元测试,再决定哪些行为值得通过公开 API 做更高层验证。这样既能保留对内部规则的精确检查,也能让生产代码的可见性保持在真正需要的范围内。