Go testing.T.Output 的并发日志写入与刷新边界

测试里需要输出一段多行诊断信息时，testing.T.Output() 比连续调用 Logf 更适合复用：它返回一个 io.Writer，不替你添加源码位置和换行，内部按行缓冲。实际使用时，把 Writer 只留在测试生命周期内；多个 goroutine 共享它时，按“完整记录”加锁写入，避免一条记录被拆开。

先分清 Output、Log 和 Logf 的职责

t.Output() 返回的 Writer 写入同一测试输出流，但不会像 t.Log 那样自动添加源码位置或换行。它更像一个“可交给格式化器”的出口：JSON、表格、分段诊断都可以连续写入。官方文档还说明，Writer 内部按行缓冲，调用 Log/Logf 或测试结束时会刷新当前缓冲，并补上换行。

在测试体内写入多行诊断内容

把 Writer 在测试函数内部取得，并把它传给真正负责格式化的函数。下面的示例写入一段稳定的键值诊断，同时保留显式换行。代码中的注释只解释关键边界，不把图示当成运行截图。

package report

import (
    "fmt"
    "io"
    "testing"
)

func writeReport(w io.Writer, name string, count int) error {
    // Output 不会自动补换行，所以多行内容要由调用方明确分隔。
    _, err := fmt.Fprintf(w, "name=%s\\ncount=%d\\n", name, count)
    return err
}

func TestReport(t *testing.T) {
    out := t.Output()
    if err := writeReport(out, "cache", 3); err != nil {
        // Writer 出错时直接让测试失败，避免把不完整诊断当成成功结果。
        t.Fatalf("write report: %v", err)
    }
}

在普通测试中，失败时或使用详细输出时才能看到相应日志；基准测试的输出规则不同，不要用另一种测试类型的观察方式反推 T.Output 的行为。

多个 goroutine 写 Output 时，先保证记录完整

并发场景真正需要防的是“记录内部交错”。不要让一个 goroutine 分三次写入同一条日志、另一个 goroutine 在中间插入内容。调用方可以把一条记录先组装成字符串，再用互斥锁完成一次写入；这是一种工程层的组织方式，不应解读成 Output 对多次 Write 自动提供原子性。

package report

import (
    "fmt"
    "io"
    "sync"
    "testing"
)

type testWriter struct {
    mu sync.Mutex
    w  io.Writer
}

func (tw *testWriter) record(name string, value int) error {
    // 先拼成一条完整记录，再在锁内一次写出，避免多次 Write 互相穿插。
    line := fmt.Sprintf("name=%s value=%d\\n", name, value)
    tw.mu.Lock()
    defer tw.mu.Unlock() // 无论 Write 是否报错，都释放锁。
    _, err := io.WriteString(tw.w, line)
    return err
}

func TestConcurrentReport(t *testing.T) {
    tw := &testWriter{w: t.Output()}
    var wg sync.WaitGroup
    for i := 0; i 

刷新和生命周期边界要一起处理

行缓冲意味着“Write 返回”不等于“马上看到一条完整终端行”。只要后续调用 Log/Logf，或者测试函数自然结束，缓冲就会被刷新；因此不要为了强行 flush 而把 Writer 转成不受支持的具体类型。更重要的是，测试函数及所有父测试返回后，Output 和它的 Write 都不能再调用。

如果后台 goroutine 还在运行，测试却已经返回，问题不在刷新参数，而在生命周期设计。用 WaitGroup 或上下文取消先收拢后台任务，再让测试函数返回；这样每次写入都发生在明确的有效区间内。

常见问题

Output Writer 会自动给每行加换行吗？

不会。Write 写入什么就保留什么；需要多行时在格式化内容里显式加入 \\n。

能在测试结束后的 goroutine 里继续写吗？

不能。测试函数和父测试都返回后，Writer 及其 Write 方法不再可用；应先等待或取消后台任务。

为什么调用 Logf 后之前的内容才出现？

因为 Output 内部按行缓冲，Log/Logf 会隐式刷新当前缓冲并追加换行。不要把这种现象当成 Write 丢数据。

排查这类输出问题时，按“是否显式换行—是否记录级同步—测试是否等待后台任务”的顺序检查，通常比调整日志格式更快找到边界。