Go / 系统课时
组织测试文件与包
组织测试文件与包
Go 的测试边界首先由文件名和 package 声明决定。把测试放进同包可以检查未导出实现,把测试放进 <包名>_test 则只能通过公开 API 观察行为。本节用一个最小模块同时放置两类测试,明确什么时候该看内部细节,什么时候应坚持黑盒边界。
学习目标
- 掌握
_test.go文件的发现规则与测试函数的基本命名约定。 - 区分同包测试和外部测试包在可见性、依赖关系和测试视角上的差异。
- 能根据测试目标选择包组织方式,并用
go test验证目录结构。
测试文件由命名规则进入工具链
测试源码必须以 _test.go 结尾,例如 calculator_test.go。这些文件不会参与普通 go build 生成的库或可执行文件,但运行 go test 时会和被测包一起参与测试构建。
在测试文件内,TestXxx 接收 *testing.T,BenchmarkXxx 接收 *testing.B,FuzzXxx 接收 *testing.F。文件名负责把源码交给测试工具链,函数命名与签名再决定它属于哪类测试入口。
同包与外部包形成两种观察位置
假设模块名是 example/mathx。同包测试声明 package mathx,因此和生产代码处在同一个包作用域,可以直接访问未导出的 normalize。外部测试声明 package mathx_test,它会像真正的调用方一样导入 example/mathx,只能使用导出标识符。

片段示例:下面四个文件共同构成一个可运行模块,单个文件不独立执行。
go.mod:
module example/mathx
go 1.20calculator.go:
package mathx
func normalize(n int) int {
if n < 0 {
return -n
}
return n
}
func Add(a, b int) int {
return normalize(a) + normalize(b)
}calculator_internal_test.go 使用同包测试,直接验证内部不变量:
package mathx
import "testing"
func TestNormalize(t *testing.T) {
if got := normalize(-3); got != 3 {
t.Fatalf("normalize(-3) = %d, want 3", got)
}
}calculator_external_test.go 使用外部测试包,只验证公开行为:
package mathx_test
import (
"testing"
"example/mathx"
)
func TestAdd(t *testing.T) {
if got := mathx.Add(-2, 3); got != 5 {
t.Fatalf("Add(-2, 3) = %d, want 5", got)
}
}用一次测试确认两种包都能工作
在模块根目录执行:
go test -v预期输出会分别显示同包测试和外部包测试通过;耗时是动态值:
=== RUN TestNormalize
--- PASS: TestNormalize (<TIME>s)
=== RUN TestAdd
--- PASS: TestAdd (<TIME>s)
PASS
ok example/mathx <TIME>sTestNormalize 能直接调用 normalize,因为它与生产代码同属 mathx。TestAdd 必须写成 mathx.Add,因为 mathx_test 是另一个包;如果它尝试访问 mathx.normalize,编译阶段就会因为标识符未导出而失败。
按测试目的选择边界
同包测试适合验证内部算法、不易通过公开 API 精确观察的状态,以及需要针对实现细节建立回归保护的代码。代价是测试更了解内部结构,重构时更容易一起修改。
外部测试包更接近真实使用者,适合验证公开 API、示例行为和包级契约。它天然阻止测试依赖未导出实现,因此更能发现“内部测试全绿,但外部调用方式已经破坏”的问题。
两种方式可以在同一个目录并存,不必二选一。通常让公开契约优先放在 package xxx_test,只有确实需要检查内部不变量时再补充 package xxx 测试,就能同时获得黑盒稳定性和必要的白盒覆盖。