Ginkgo 的 Describe 和 It 不能直接写在包顶层，因为它们依赖运行时注册机制，必须包裹在 func TestXxx(t *testing.T) 函数体内，由 RunSpecs 扫描并执行；否则会 panic：“failed to run spec: no tests registered”。
为什么 Ginkgo 的 Describe 和 It 不能直接写在包顶层
Ginkgo 不是普通 Go 测试框架，它依赖运行时注册机制。所有 Describe、It、BeforeEach 必须包裹在 func TestXxx(t *testing.T) 函数体内，否则会 panic："failed to run spec: no tests registered"。这不是语法错误，而是 Ginkgo 初始化失败——它靠 RunSpecs 扫描当前测试函数里注册的 spec 树。
正确写法是：
func TestMySuite(t *testing.T) {
RegisterFailHandler(Fail)
RunSpecs(t, "My Suite")
}然后在同一个文件（或 _test.go 文件）中写：
var _ = Describe("UserService", func() {
var service *UserService
<pre class="brush:php;toolbar:false;">BeforeEach(func() {
service = NewUserService()
})
It("returns error when email is empty", func() {
_, err := service.CreateUser("", "pwd123")
Expect(err).To(HaveOccurred())
})})
BeforeSuite 和 AfterSuite 适合做什么
它们只执行一次，且跨所有 Describe 块，常用于启动/关闭共享资源。但注意：它们运行在主 goroutine，不能阻塞；若启协程，需自己管理生命周期。
-
BeforeSuite适合初始化数据库连接池、启动 mock HTTP server（如httptest.NewServer）、加载配置 -
AfterSuite必须显式关闭资源，比如调用server.Close()或db.Close()；漏掉会导致测试间污染或端口占用 - 不要在
BeforeSuite里做耗时操作（如拉镜像、下载大文件），会拖慢整个测试套件启动 - 若测试并行运行（
ginkgo -p），BeforeSuite仍只跑一次，但无法保证它比某个It先完成——别在里面写依赖单个测试状态的逻辑
如何让 It 支持异步逻辑和超时控制
Ginkgo 原生支持异步测试，但必须用 It 的闭包参数接收 Done，并在完成时调用 close(done)。不这样做，测试会立即超时失败（默认 1 秒）。
示例：
It("fetches user data asynchronously", func(done Done) {
go func() {
defer close(done)
resp, err := http.Get("http://localhost:8080/user/123")
Expect(err).NotTo(HaveOccurred())
Expect(resp.StatusCode).To(Equal(200))
}()
})超时可单独设置：
It("times out after 5 seconds", func(done Done) {
timeout := time.After(5 * time.Second)
go func() {
select {
case <-time.After(3 * time.Second):
close(done)
case <-timeout:
Fail("operation took too long")
}
}()
})常见坑：
- 忘记
close(done)→ 测试卡住直到全局超时（默认 60 秒） - 在 goroutine 外调用
close(done)→ 竞态或 panic - 用
time.Sleep模拟异步但没配done→ 测试误判为同步执行，可能跳过断言
为什么 Context 只是 Describe 的别名，但建议少用
Context 是 Ginkgo 提供的语义别名，等价于 Describe，源码里就是 type Context = Describe。它本意是强化 BDD 场景描述（如 Context("when user is admin")），但实际带来两个问题：
- IDE 和静态分析工具（如 gopls）可能不识别
Context为测试块入口，导致代码折叠、跳转异常 - 团队协作时容易混淆：有人用
Describe写层级，有人用Context写条件，结构松散难维护 - Ginkgo v2+ 文档已弱化
Context推荐，官方示例统一用Describe
更稳妥的做法是：统一用 Describe 表达测试主题，用 When（也是别名）或注释说明条件分支，例如：
Describe("User creation", func() {
When("email is malformed", func() {
It("returns validation error", func() { /* ... */ })
})
})Ginkgo 的 BDD 风格真正难的不是语法，而是把业务逻辑的“场景-行为-断言”映射到嵌套的 Describe/It 结构里；很多人卡在写完第一个 It 后发现 setup 重复、状态难复位，这时候该想的不是加更多 BeforeEach，而是拆分测试文件或重构被测对象的接口边界。
