ginkgo 测试 panic 的主因是未调用 runspecs：每个测试文件须有 func testxxx(t *testing.t)，其中先 registerfailhandler(fail)，再唯一调用 runspecs(t, “suite”)；否则框架不启动、断言不执行或 panic。
为什么 Ginkgo 测试一跑就 panic：没调用 RunSpecs
Go 的 BDD 测试不是靠 go test 自动发现的——Ginkgo 用的是自定义测试入口。漏掉 RunSpecs，整个 Describe/It 块根本不会执行，看起来像“没跑测试”，其实是压根没启动测试框架。
常见错误现象：go test 输出 ok ./pkg 0.001s，但一个断言都没触发；或者直接 panic 报 no tests to run（尤其在非标准包名下）。
- 每个测试文件必须有
func TestXxx(t *testing.T)入口函数 - 该函数里必须调用
RunSpecs(t, "描述文字")，且只调一次 - 不要在
init()或包级变量初始化里调用RunSpecs，会破坏go test生命周期 - 如果用了
ginkgo run命令，则不需要手写TestXxx，但此时不能混用go test
func TestMySuite(t *testing.T) { RegisterFailHandler(Fail) RunSpecs(t, "MySuite Suite") }Gomega 断言失败时不显示具体值：忘记注册 Fail 处理器
Gomega 本身不直接输出失败详情，它依赖你传给 RegisterFailHandler 的函数来抛出错误。没注册，或注册了但函数没正确转发 t.Fatal，就会看到空 panic 或 “test timed out” 这类误导信息。
使用场景：任何用 Expect(...).To(Equal(...)) 的地方，一旦失败，你得立刻知道 实际值 和 期望值 差在哪。
立即学习“go语言免费学习笔记（深入）”；
- 必须在
TestXxx函数里、RunSpecs之前调用RegisterFailHandler(Fail) -
Fail来自github.com/onsi/ginkgo/v2，不是标准库的testing.T.Fail - 别写成
RegisterFailHandler(t.Fail)——t在 handler 里不可用，会 panic - 如果用了
ginkgo run，Fail默认已注册，但手动go test时这步绝不能省
并发测试里 BeforeSuite 和 BeforeEach 混用导致状态污染
Ginkgo 默认并行运行 It，而 BeforeSuite 只执行一次（适合 DB 连接、端口绑定），BeforeEach 每个 It 前都执行（适合重置内存状态）。错把本该隔离的资源放 BeforeSuite，多个 It 就会争抢同一份数据。
典型错误现象：单测全过，一加 -p 4 就随机失败；It 之间出现 “connection refused” 或 “key already exists”。
- 全局共享资源（如 http server、数据库连接池）放
BeforeSuite，但要确保线程安全或带锁访问 - 每个测试独占资源（如临时文件、map、mock 对象）必须在
BeforeEach里初始化 - 避免在
BeforeSuite里写入可变全局变量，比如var db *sql.DB然后在It里改它的状态 - 用
ginkgo --dry-run看实际执行顺序，确认生命周期是否符合预期
从 go test 切到 ginkgo 命令后，-race 不生效
ginkgo CLI 是独立二进制，它调用 go test 时默认不透传所有 flag。直接 ginkgo -race 会报错或静默忽略，导致竞态检测失效——这是上线前最危险的盲区之一。
性能 / 兼容性影响：竞态检测开销大，但线上踩坑成本更高；不用 -race 的 BDD 测试可能掩盖真实并发 bug。
- 正确写法是
ginkgo -r -p -race（-r递归，-p并行，-race开启检测） - 注意
ginkgov2 要求 Go 1.16+，旧版ginkgo（v1）不支持-race直接透传 - CI 中建议统一用
ginkgo命令而非go test，否则容易漏掉GINKGO_*环境变量控制行为 - 如果项目同时存在
go test和ginkgo两种运行方式，务必在文档里写清各自启用-race的准确命令
最常被忽略的其实是 RunSpecs 和 RegisterFailHandler 的调用顺序——差一行位置，测试就变成“假通过”。BDD 的表达力再强，底层还是靠这两句胶水粘住。