Go testing/iotest.TimeoutReader 怎样测试读超时

写网络流或自定义协议测试时，我更愿意把“等待几秒才超时”换成可重复的读序列。Go 标准库的 testing/iotest.TimeoutReader 正好适合这个场景：它不等待真实时间，而是在底层 Reader 出现无数据读取时，制造一次 iotest.ErrTimeout，后面的读取再交还给底层 Reader。

官方地址：https://pkg.go.dev/testing/iotest#TimeoutReader

最小测试方式是：把一个可控 Reader 包成 iotest.TimeoutReader，先读出一段数据，再让底层返回 0, nil，断言下一次读取得到 iotest.ErrTimeout；随后再读一次，确认它不再重复伪造同一个超时。

先把 Reader 包成可控的测试对象

TimeoutReader 接收并返回 io.Reader。因此测试重点不是网络连接，而是准备一个能精确控制每次 Read 返回值的 Reader。下面的 scriptedReader 依次返回数据、无数据和另一段数据，方便把三个状态放进同一个测试。

package timeoutreader_test

import (
    "io"
)

// readResult 描述一次可预先安排的 Read 返回值。
type readResult struct {
    data []byte
    err  error
}

// scriptedReader 只用于测试，按 results 的顺序返回每次读取结果。
type scriptedReader struct {
    results []readResult
    index   int
}

func (r *scriptedReader) Read(p []byte) (int, error) {
    // 序列耗尽后遵守 Reader 的结束约定，返回 EOF。
    if r.index >= len(r.results) {
        return 0, io.EOF
    }
    result := r.results[r.index]
    r.index++

    // 只复制调用方缓冲区能容纳的数据，保持 Read 的边界。
    n := copy(p, result.data)
    return n, result.err
}

用调用次数断言超时与恢复

下面的测试把第二个结果安排为 0, nil。这不是一个真实的网络超时，而是 Reader 告诉上层“这次没有数据，也没有最终错误”。TimeoutReader 会把这个特定位置转换成 iotest.ErrTimeout，正适合覆盖调用方的重试或超时分支。

package timeoutreader_test

import (
    "errors"
    "testing"
    "testing/iotest"
)

func TestTimeoutReader(t *testing.T) {
    source := &scriptedReader{results: []readResult{
        {data: []byte("hello")}, // 第一次读取：先提供正常数据。
        {},                       // 第二次读取：0, nil，模拟暂时无数据。
        {data: []byte("world")}, // 后续读取：确认超时错误不会永久粘住。
    }}
    reader := iotest.TimeoutReader(source)
    buf := make([]byte, 5)

    n, err := reader.Read(buf)
    if n != 5 || err != nil {
        t.Fatalf("第一次读取 = (%d, %v)，想要 (5, nil)", n, err)
    }

    n, err = reader.Read(buf)
    // 用 errors.Is 判断哨兵错误，不要依赖错误文本。
    if n != 0 || !errors.Is(err, iotest.ErrTimeout) {
        t.Fatalf("第二次读取 = (%d, %v)，想要 (0, ErrTimeout)", n, err)
    }

    n, err = reader.Read(buf)
    if n != 5 || err != nil || string(buf) != "world" {
        t.Fatalf("恢复读取 = (%d, %v, %q)，想要 (5, nil, world)", n, err, buf)
    }
}

这个断言有三个关键点：第一次读取确认输入数据确实到达；第二次同时检查 n == 0 和 ErrTimeout；第三次确认包装器没有把后续所有读取都变成超时。

为什么不要用错误字符串判断

iotest.ErrTimeout 是公开的哨兵错误。测试应使用 errors.Is，这样即使调用链未来用包装错误补充上下文，断言仍然表达“这是超时分支”这一意图。与此同时，Read 的返回值仍要检查：超时分支必须是 n == 0，不能只看错误而忽略已经写入缓冲区的字节。

如果待测代码会把超时包装成自己的错误，可以在待测函数返回后继续用 errors.Is(err, iotest.ErrTimeout) 追踪根因；如果它把错误转换成业务状态，就应断言业务状态和重试次数，而不是强迫业务层暴露底层错误文本。

几个容易写错的边界

• 把它当成计时器：TimeoutReader 不会等待指定秒数，也不接收 duration。它模拟的是 Reader 读不到数据时的错误分支。
• 只准备一个空 Reader：这样很难区分“第一次就没有数据”和“第二次无数据”。最好用脚本 Reader 明确安排调用序列。
• 断言后续仍然是超时：官方语义是第二次无数据读取返回 ErrTimeout，后续调用会继续读取底层 Reader。恢复阶段应按底层实际返回值断言。
• 忽略 n：Reader 合同同时包含字节数和错误。即使某些实现允许 n > 0 与错误同时出现，测试也应明确当前分支期望的字节数。

小结：把超时分支变成确定的读序列

测试读超时时，可以用 iotest.TimeoutReader 包住一个可控的 io.Reader：先安排正常数据，再安排一次 0, nil，断言第二次读取返回 iotest.ErrTimeout，最后检查后续读取已经回到底层语义。这样测试快速、稳定，也不会因为机器负载或网络环境变化而随机失败。

相关问题

TimeoutReader 会真的等待超时时间吗？不会，它是测试用 Reader，目标是制造超时错误分支，不是测量 wall-clock 时间。

为什么第三次读取不能固定断言 EOF？因为第三次结果取决于底层 Reader。本例安排了 world，换成 bytes.Reader 时则可能得到数据耗尽后的 io.EOF。