# Timeouts And Async

Make Ginkgo specs interruptible and test asynchronous behavior, ...

- Repository: https://github.com/onsi/ginkgo (9071 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-09
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add onsi/ginkgo --skill timeouts-and-async -g -a claude-code -y`
Codex: `npx skills add onsi/ginkgo --skill timeouts-and-async -g -a codex -y`
Cursor: `npx skills add onsi/ginkgo --skill timeouts-and-async -g -a cursor -y`
Gemini CLI: `npx skills add onsi/ginkgo --skill timeouts-and-async -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add onsi/ginkgo`

## Description

Make Ginkgo specs interruptible and test asynchronous behavior, SpecContext/context.Context cancellable nodes, NodeTimeout/SpecTimeout/GracePeriod, the --timeout flag, Abort and SIGINT behavior, Gomega Eventually/Consistently (the func(g Gomega) form, .WithContext), and the defer GinkgoRecover() rule for goroutines. Use when a spec hangs or times out, polls for eventual consistency, tests channels/streams/processes, launches goroutines, or needs a deadline.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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:

```go
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`)

| Decorator | Scope |
|---|---|
| `NodeTimeout(d)` | Deadline for **one** interruptible node. |
| `SpecTimeout(d)` | Deadline for the whole spec lifecycle, **`It` only**. |
| `GracePeriod(d)` | How long Ginkgo waits after cancelling before leaking the node. |

The rest: https://github.com/onsi/ginkgo/blob/HEAD/plugins/ginkgo/skills/timeouts-and-async/SKILL.md