timeouts-and-async

Timeouts, interruptible nodes, and async testing

Builds on the failure mental model in ginkgo:overview (failure is a panic Ginkgo recovers; a goroutine that fails needs defer GinkgoRecover()). Docs: https://onsi.github.io/ginkgo/#spec-timeouts-and-interruptible-nodes and https://onsi.github.io/ginkgo/#patterns-for-asynchronous-testing.

Interruptible nodes: take a context, honor cancellation

A setup or subject node becomes interruptible simply by accepting a SpecContext (or plain context.Context) — Ginkgo supplies one automatically:

It("likes to sleep in", func(ctx context.Context) {
  select {
  case <-ctx.Done(): return        // honor cancellation and exit promptly
  case <-time.After(time.Hour): ...
  }
}, NodeTimeout(time.Second))

On timeout or interrupt, Ginkgo cancels the context to tell the node to stop. Pass ctx down into every blocking call (libraryClient.SaveBook(ctx, book), exec.CommandContext(ctx, ...)) so the cancellation actually propagates. Only setup/subject nodes are interruptible — container nodes are not (they run at construction time).

• ctx.Deadline() does NOT report the node's deadline. Ginkgo manages cancellation timing itself (to snapshot a progress report first), so it does not use a WithDeadline context. Trust <-ctx.Done(), not Deadline().
• SpecContext satisfies context.Context; you may wrap it (context.WithValue) and Ginkgo still cancels the result on time.

The timeout decorators (full reference → ginkgo:decorators)

• SpecTimeout can only be more lenient than a node's NodeTimeout — it caps the sum of all nodes (BeforeEach+It+AfterEach); a per-node NodeTimeout inside it is always more stringent.
• Cleanup still runs after a timeout. When SpecTimeout fires, Ginkgo cancels the current node, then runs AfterEach/AfterAll/DeferCleanup (each under its own NodeTimeout/grace). The timeout is a "mark failed" threshold, not a hard kill.
• A node that ignores cancellation is "leaked," not killed. After the grace period Ginkgo gives up waiting and moves on. Leaking is deliberately preferred over hanging forever — but a leaked goroutine keeps running and can call Fail/AddReportEntry and pollute a later spec. Always make blocking code respond to ctx.Done().
• DeferCleanup/DescribeTable entries are interruptible too — give the cleanup/entry func a ctx first arg; don't capture and reuse the parent node's ctx (it's already cancelled by cleanup time).