测试偶发失败但本地无法复现，怎样记录随机种子与执行顺序

CI 上某个 Go 测试一周失败两次，本地连跑几百次都正常，最容易犯的错误是只截下一行断言失败。真正可复现的记录至少要包含两套种子：测试数据使用的 case seed，以及 go test -shuffle 使用的顺序 seed；还要记录测试名、参数和程序计划的用例顺序。少其中一项，本地重放的就可能是另一场测试。

Go 测试命令说明可参考 https://pkg.go.dev/cmd/go/internal/test，伪随机数说明可参考 https://pkg.go.dev/math/rand。官方文档说明，-shuffle=on 会用系统时钟生成种子，-shuffle=N 使用给定整数；开启乱序时种子会输出，供后续复现。

保护资产：失败现场最小需要保存什么

偶发测试的核心资产不是完整 CI 日志，而是能重新构造失败条件的“复现胶囊”。我会固定保存：包路径、完整测试名、case seed、shuffle seed、命令参数、输入摘要、计划顺序、并行度、Go 版本和关键环境开关。敏感连接串、令牌和业务数据不应原样进入日志，可以记录脱敏摘要或哈希。

攻击路径：四类不确定性不要混成一个种子

第一类是测试代码显式使用的 math/rand，它可以被 case seed 控制。第二类是 go test -shuffle，它控制测试程序里的顶层测试和基准测试顺序，是另一套随机器。第三类是 map 迭代顺序，它不受你的 rand.Rand 控制。第四类是 goroutine 调度、时钟、网络和外部服务状态，即使种子相同也未必完全一致。

因此，“我已经记录 seed”还不够。需要说明这个 seed 控制什么，哪些因素没有被它控制。尤其不要依赖 map 遍历产生测试顺序；如果顺序本身需要重放，应先提取键并排序，或者用显式局部随机器打乱切片。

风险分级：先判断是哪一种偶发失败

如果固定 case seed 后每次都失败，风险集中在输入生成或业务逻辑。如果固定 shuffle seed 后才失败，通常说明测试之间共享了包级状态、环境变量、端口或全局客户端。如果单线程可以重现、并行时才漂移，要优先检查竞争和生命周期。如果任何种子都无法稳定重现，则把注意力转向真实时间、超时、网络、文件系统和外部服务。

这个分类能避免无效尝试：数据错误不必先追 goroutine；共享状态问题也不应该通过“再随机几次”碰运气。固定一个变量、保留另一个变量，是缩小范围最快的办法。

防护控制：为测试数据建立局部随机源

可重放测试不要调用包级 rand.Intn 后再指望全局 rand.Seed 修复。官方文档已将 rand.Seed 标记为弃用，并说明 Go 1.24 起它默认是无操作。需要确定序列时，应创建局部 rand.Rand。

package planner_test

import (
    "flag"
    "math/rand"
    "testing"
    "time"
)

var caseSeed = flag.Int64(
    "case-seed",
    time.Now().UnixNano(),
    "测试数据随机种子",
)

func TestPlanner(t *testing.T) {
    // 局部随机源只服务当前测试，给定同一 seed 会产生同一序列
    rng := rand.New(rand.NewSource(*caseSeed))

    cases := makeCases(rng)

    // 先保存实际计划顺序，失败时无需再次猜测
    order := make([]string, 0, len(cases))
    for _, tc := range cases {
        order = append(order, tc.Name)
    }
    t.Logf("repro case_seed=%d planned_order=%q", *caseSeed, order)

    for _, tc := range cases {
        tc := tc
        t.Run(tc.Name, func(t *testing.T) {
            // 子测试只消费已经冻结的输入，不再调用共享随机源
            verifyCase(t, tc)
        })
    }
}

不要从多个并行子测试共享同一个局部 *rand.Rand；NewSource 返回的 Source 本身不保证并发安全。更稳妥的办法是在父测试中先生成所有输入，再把不可变测试用例交给子测试。若每个子测试必须独立随机生成数据，可以用主 seed 和子测试稳定标识派生各自的 seed，并逐个记录。

防护控制：用显式 shuffle seed 控制测试顺序

-shuffle=on 适合在 CI 主动探索顺序依赖，因为 Go 会生成并报告一个 seed。发现失败后，把输出中的值改成 -shuffle=N 即可重放。为了让 CI 产物更直接，我更偏向由作业生成一个整数，同时传给 case seed 和 shuffle seed；两者数值可以相同，但仍是两个独立控制面。

# CI 探索：让 go test 生成并报告顶层测试乱序种子
go test ./... -shuffle=on -count=1 -v

# 本地重放：固定顶层顺序和测试数据，并关闭测试缓存影响
go test ./planner \
  -run '^TestPlanner$' \
  -shuffle=784233 \
  -count=1 \
  -v \
  -args -case-seed=991827

-count=1 让这次诊断明确执行测试而不是复用缓存。-run 尽量缩小到完整测试名；若失败依赖另一个顶层测试先运行，就保留那组测试的共同正则，或先用固定 shuffle seed 重放整个包，再逐步缩小。

审计记录：失败时输出一份复现胶囊

仅在测试开头打印 seed 可能被海量成功日志淹没。更实用的做法是维护一个轻量记录对象：平时用 t.Logf 输出，在失败分支再次用 t.Errorf 附上同一份字段。CI 必须保留标准输出或 go test -json 结果，否则 Go 已报告的 shuffle seed 仍可能丢失。

type reproInfo struct {
    CaseSeed    int64
    TestName    string
    Package     string
    Planned     []string
    Parallelism int
}

func (r reproInfo) Log(t *testing.T) {
    t.Helper()

    // 字段名保持稳定，便于 CI 收集器提取和生成复现命令
    t.Logf(
        "repro package=%s test=%s case_seed=%d parallel=%d planned_order=%q",
        r.Package,
        r.TestName,
        r.CaseSeed,
        r.Parallelism,
        r.Planned,
    )
}

测试代码无法通过稳定公开 API 直接读取 -shuffle 的最终种子，所以不要依赖测试内部“反查”。让 go test 自己报告，或者由 CI 显式生成并保存 -shuffle=N。这也让日志职责更清楚：测试记录输入与内部顺序，测试命令记录顶层顺序。

验证清单：同样种子仍不复现时怎么查

• 确认命令中的包、完整测试名、case seed 和 shuffle seed与失败记录一致。
• 添加 -count=1，避免误把缓存结果当成重放结果。
• 临时用 -parallel=1 判断问题是否依赖并行调度。
• 用 -race 检查共享内存竞争；种子不能固定 goroutine 交错。
• 把 map 键复制到切片并排序，不把 map 迭代当作可控随机源。
• 记录时区、Go 版本、CPU 数、关键环境开关和外部服务版本。
• 替换真实时钟、随机 UUID 和网络调用，给测试注入可控依赖。

# 缩小并行因素：固定种子并把包内并行测试上限降为 1
go test ./planner \
  -run '^TestPlanner$' \
  -shuffle=784233 \
  -parallel=1 \
  -count=1 \
  -race \
  -v \
  -args -case-seed=991827

需要强调：相同种子只能重放受该种子控制的选择，不能承诺重放操作系统调度、网络抖动或真实时间。如果固定输入和顶层顺序后仍然漂移，这不是记录失败，而是证据告诉你问题已经进入并发或环境域。

常见问题

-shuffle=on 的种子在哪里看？

开启乱序后，Go 测试程序会在输出中报告 -test.shuffle 及整数值。CI 要保留测试标准输出或 JSON 测试事件，失败后把该整数用于 -shuffle=N。

一个 seed 能同时控制随机数据和测试顺序吗？

不能自动控制。可以把同一个整数分别传给 rand.NewSource 和 -shuffle，但它们仍是两套独立随机器，日志中应分别命名。

为什么固定 seed 后 map 遍历顺序仍然变了？

Go 的 map 迭代不由 math/rand 控制。需要稳定顺序时提取并排序键；需要可重放乱序时，对排序后的切片使用自己的局部随机器。

重复运行偶发测试应该用多大的 count？

探索阶段可以提高 -count，但一旦出现失败，应立即保存那次的所有复现字段。次数越多不等于证据越好，能固定并缩小失败条件才是目标。