Go test -failfast 怎样在首个测试失败后停止

我在排查一组互相独立的 Go 测试时，最先想要的通常不是“收集全部失败”，而是尽快知道第一个破坏测试前提的用例是谁。此时可以使用 go test -failfast：它会在首个测试失败后不再启动新的测试，但已经开始运行的测试，尤其是并行测试，仍可能继续收尾。

这个边界很重要。-failfast 是快速定位开关，不是强制终止进程的 kill 开关。对我来说，最稳妥的用法是把它放在本地排障或快速门禁里；需要完整失败清单时，再运行一次不带它的全量测试。

官方地址：https://pkg.go.dev/cmd/go

先判断 -failfast 解决的是什么问题

官方对这个参数的定义很直接：首个测试失败后，不再启动新的测试。这里的“新的”决定了它的使用边界。串行测试中，后续尚未开始的用例会被跳过；已经进入执行状态的用例不会因为参数突然失败就被强行打断。

# 先用快速模式找到最早暴露问题的测试。
go test -failfast ./...

# 只针对一个包重跑，减少其他包的输出干扰。
go test -failfast ./internal/order

# 完整回归时去掉 -failfast，收集同一批次的全部失败。
go test ./...

我通常把这三个命令看成同一条排查链：第一条回答“最早失败在哪里”，第二条回答“这个包能否稳定复现”，第三条回答“修复后还有没有其它独立问题”。如果把第三条也固定成 -failfast，很容易把一个失败误判成全部结果。

串行与并行测试的停止边界

测试运行时需要同时管理待启动的测试、已经运行的测试和清理回调。-failfast 影响的是测试调度策略，不会把已经拿到执行机会的并行用例变成未运行状态。

下面这个最小示例只用于说明关系，不代表本文已经执行过它。父测试把子测试交给 t.Run，子测试再决定是否调用 t.Parallel。当某个测试失败后，调度器可以停止继续启动尚未开始的测试，但已经运行的并行测试仍有自己的函数体和清理逻辑。

package failfast_test

import "testing"

func TestOrders(t *testing.T) {
    cases := []struct {
        name string
        ok   bool
    }{
        {name: "valid", ok: true},
        {name: "broken", ok: false},
        {name: "later", ok: true},
    }

    for _, tc := range cases {
        tc := tc // 为每个子测试固定当前样本，避免闭包读取变化中的循环变量。
        t.Run(tc.name, func(t *testing.T) {
            // 并行子测试可能已经开始；failfast 不保证它在失败瞬间被中止。
            t.Parallel()
            t.Cleanup(func() {
                // 清理属于已开始测试的收尾，不应被当成新的测试启动。
            })
            if !tc.ok {
                t.Fatal("订单状态不符合预期")
            }
        })
    }
}

因此，看到 -failfast 之后仍有少量日志或清理动作，并不等于参数失效。真正要确认的是：首个失败之后，尚未开始的测试是否没有再启动；而不是要求所有已开始的 goroutine 立即消失。

按诊断目标组合 go test 参数

只加一个 -failfast 往往还不够。实际排查时，我会先缩小包和测试名，再决定是否关闭缓存，最后保留结构化事件。参数越多，解释结果时越要记下它们改变了什么。

# 先锁定包和失败分支，再关闭缓存并保存事件流。
go test -count=1 -failfast -run 'TestOrders/.*broken' -json ./internal/order

# 需要判断共享状态时，单独增加竞态检测；它会改变运行成本。
go test -count=1 -race -run 'TestOrders' ./internal/order

# 需要完整回归报告时，去掉 -failfast，但保留 -json 供 CI 归档。
go test -count=1 -json ./...

这几条命令解决的是不同问题：-run 负责范围，-count=1 负责缓存，-race 负责共享内存风险，-json 负责记录。不要把它们混成“更严格的一个开关”，否则失败原因和参数副作用会纠缠在一起。

把快速定位和完整收集拆成两种门禁

如果团队只有一条测试流水线，大家很容易在速度和信息量之间反复争论。我的做法是拆成两种目的明确的门禁：提交前或本地复现使用 -failfast，合并前或夜间回归不使用它。两者使用同一份代码和依赖，只改变调度策略。

#!/usr/bin/env bash
set -euo pipefail

# 快速门禁只负责尽快暴露第一个阻断问题。
go test -count=1 -failfast -json ./... | tee test-fast.json

# 完整门禁单独运行，负责收集所有失败；由 CI 保存事件文件。
go test -count=1 -json ./... | tee test-full.json

如果资源有限，可以先运行快速门禁，失败就直接保存 test-fast.json；如果快速门禁通过，再按流水线预算决定是否做完整回归。需要注意的是，两个命令都可能受到外部服务、工作目录、环境变量和共享端口影响，所以门禁脚本还应输出 Go 版本、模块路径和目标平台。

• 只想尽快找到根因：使用 -failfast，并缩小到单个包或测试。
• 想知道所有独立回归：去掉 -failfast，保留 -json。
• 怀疑旧结果：增加 -count=1，不要把它误解为修复开关。
• 怀疑共享状态：用 -race 做单独诊断，并接受更高运行成本。

-failfast 会不会停止已经运行的并行测试？ 不应这样理解。它阻止新的测试启动；已经开始的测试可能继续运行并执行清理。

为什么快速门禁通过，完整门禁仍然失败？ 可能是后续测试暴露了独立问题，也可能是测试之间共享了状态。此时应比较结构化事件和测试顺序，而不是直接认定 -failfast 造成了失败。

最后的判断很简单：把 -failfast 当作“先找到第一块倒下的多米诺骨牌”，不要当作“让整条测试流水线立刻断电”。理解这个边界后，本地排障会更快，CI 的完整结果也不会被牺牲。