Go testing.T.Context 与 context.WithTimeout 哪个控制测试截止

这两个 API 不是二选一：testing.T.Context()负责把 Context 绑定到测试生命周期，context.WithTimeout负责给某一次操作再收紧时间预算；go test -timeout则是测试进程级的总保险。测试需要让后台 goroutine 随测试结束而停，用 t.Context()；需要让一次请求、轮询或重试最多运行一段时间，用 context.WithTimeout(t.Context(), ...)。

官方文档：https://pkg.go.dev/testing

先分清三个“截止”

go test -timeout限制整个测试二进制的运行时间，t.Deadline()可以读取这个总截止时间。它适合防止测试整体卡死，但不会自动替业务函数传递取消信号。

t.Context()返回与当前测试绑定的 Context。官方文档说明，它会在测试开始调用 Cleanup 注册函数之前被取消，因此适合通知后台任务收尾；它不是一个按秒倒计时的独立计时器。

context.WithTimeout(parent, d)从父 Context 派生子 Context，超时或父级取消时关闭 Done，并返回一个需要调用的 cancel。它适合表达“这一次操作最多占用多久”。

后台任务用 testing.T.Context 接收结束信号

测试里启动后台任务时，直接把 t.Context()传进去，可以让任务监听同一个生命周期。测试函数返回、测试被取消或清理阶段到来时，任务都能从 Done() 收到信号。注意，取消 Context 不会替你等待 goroutine 退出，仍然要用 channel、WaitGroup 或其他同步方式完成收尾。

func TestWorkerStopsWithTest(t *testing.T) {
	ctx := t.Context()
	done := make(chan struct{})

	go func() {
		defer close(done) // 记录后台任务已经退出，便于测试收尾
		for {
			select {
			case 

这个例子中，t.Context()解决的是“什么时候通知任务结束”，Cleanup解决的是“测试怎样确认任务真的退出”。如果你要限制每轮轮询、单个 HTTP 请求或一次数据库调用的耗时，还需要继续派生子 Context。

单次操作用 context.WithTimeout 收紧预算

当测试总预算较大，但某一步不应长时间等待时，以 t.Context()作为父 Context 派生子 Context。这样既继承测试结束信号，又能让该操作更早结束；父级取消和子级超时，谁先发生都能结束操作。

func TestFetchWithinBudget(t *testing.T) {
	ctx, cancel := context.WithTimeout(t.Context(), 300*time.Millisecond)
	defer cancel() // 操作提前结束时释放计时器资源

	err := fetchData(ctx)
	if err != nil {
		if errors.Is(ctx.Err(), context.DeadlineExceeded) {
			t.Fatalf("单次操作超过预算: %v", err)
		}
		if errors.Is(ctx.Err(), context.Canceled) {
			t.Fatalf("测试生命周期已取消: %v", err)
		}
		t.Fatalf("业务调用失败: %v", err)
	}
}

判断取消原因时，优先看这个子 Context 的 Err()：如果是 DeadlineExceeded，说明单次预算先到；如果是 Canceled，通常是测试生命周期或上层主动取消。业务函数必须继续向下传递 ctx，否则超时只停留在测试代码里。

遇到“测试超时”时按边界排查

1. 总超时触发：先看 go test -timeout 是否过小，以及 t.Deadline() 是否接近当前时间；这是测试整体预算问题。
2. 单次操作没有及时返回：检查业务函数是否接收并使用 Context，尤其是 HTTP、数据库、锁等待和重试循环；只创建 WithTimeout 而不传下去没有效果。
3. 测试结束后仍有 goroutine：检查后台任务是否监听 t.Context().Done()，以及 Cleanup 是否等待退出；取消只发信号，不承担 join 语义。
4. 错误判断混乱：不要只用字符串匹配。用 errors.Is 区分 context.DeadlineExceeded 和 context.Canceled，再结合业务错误决定失败信息。

速查：到底该用哪个

常见问题

t.Context() 会让测试在超时后自动停止吗？

它能提供生命周期取消信号，但不会代替测试框架终止所有 goroutine。业务代码必须监听并响应 Context，测试本身仍由 -timeout 控制总预算。

可以直接用 context.Background() 做测试超时吗？

不建议。这样会丢失测试结束信号。更合适的写法是以 t.Context()为父级，再按操作需要调用 context.WithTimeout。