Ginkgo BDD Testing Framework for Go

Once installed, all Ginkgo skills are namespaced under ginkgo:. These skills activate automatically when working in a Go repository containing a Ginkgo suite.

It is recommended to start with ginkgo:overview to understand the mental model (tree-construction-then-run) and spec independence before using other skills.

Available skills include:

• ginkgo:overview: Mental model and routing.
• ginkgo:setup: Wiring Ginkgo into a repo (CLI, bootstrap, RegisterFailHandler, etc.).
• ginkgo:writing-specs: Authoring specs (containers, subjects, DeferCleanup).
• ginkgo:tables-and-dynamic-specs: Data-driven specs (DescribeTable, Entry).
• ginkgo:decorators: Reference for decorators.
• ginkgo:filtering: Running subsets (focus, skip, labels, filters).
• ginkgo:parallelism: Parallel execution (-p, SynchronizedBeforeSuite, sharding).
• ginkgo:ordering-and-flakes: Managing order (Ordered/Serial) and flakiness.
• ginkgo:timeouts-and-async: Async behavior and timeouts (Eventually, goroutines).
• ginkgo:running: Running suites (CLI, randomization, watching).
• ginkgo:ci: CI setup and hardening.
• ginkgo:reporting: Report files and programmatic reporters.
• ginkgo:debugging-failures: Diagnosing failures using JSON and jq.

To reuse a subset of spec behavior across different Context blocks, you can extract the It blocks into a shared-scope closure. This closure is called within the body of a Context container block during the Tree Construction Phase.

This allows the shared behavior to access variables defined in the outer scope (like a book variable) while allowing each Context to provide its own unique BeforeEach setup.

Describe("Storing books in the library", func() {
  var book *books.Book{}

  // Define the shared behavior as a closure
  AssertFailedBehavior := func() {
    It("validates that the book can't be stored", func() {
      Expect(library.IsStorable(book)).To(BeFalse())
    })

    It("fails to store the book", func() {
      Expect(library.Store(book)).To(MatchError(books.ErrStoringBook))
    })
  }

  Context("when the book has no title", func() {
    BeforeEach(func() {
      book = &books.Book{
        Author:  "Victor Hugo",
        Pages:   2783,
      }
    })

    AssertFailedBehavior() // Execute the shared behavior
  })

  Context("when the book is nil", func() {
    BeforeEach(func() {
      book = nil
    })

    AssertFailedBehavior() // Execute the shared behavior
  })
})

Ginkgo 2.0 introduces improved handling for interrupts and timeouts to ensure graceful test suite unwinding.

Interrupt Behavior

Sending an interrupt signal (e.g., Ctrl+C) now:

• Immediately causes the current test to unwind by running AfterEach blocks, skipping remaining tests, and then running the AfterSuite block.
• Emits information about the interrupted node, GinkgoWriter contents, stdout/stderr context, and a stack trace of every running goroutine.
• Does not exit immediately on a second interrupt; Ginkgo will wait until the suite has fully unwound.

Timeout Behavior

• Graceful Unwinding: Ginkgo now manages its own timeouts. When a timeout triggers, the suite winds down gracefully (running AfterEach/AfterSuite), making it functionally equivalent to a user-initiated interrupt.
• Suite-wide Timeout: In V2, the timeout applies to the entire test suite run. For example, ginkgo -r -timeout=1h guarantees the entire run exits after approximately one hour.
• Default Timeout: The default timeout has been reduced from 24h to 1h. Long-running tests in CI may require explicit adjustment via the -timeout flag.

When launching goroutines within a spec, follow these two critical rules to prevent suite crashes and hanging tests:

1. Recover from panics: Any goroutine that might call Fail or a Gomega assertion must include defer GinkgoRecover(). Without this, a failed assertion in a goroutine will cause a panic that crashes the entire test suite.
2. Poll channels, don't block on them: Do not use a bare channel receive (e.g., <-done) to wait for a goroutine. If the goroutine fails before closing the channel, the spec will hang until it times out. Instead, use Eventually(done).Should(BeClosed()) so that failures surface immediately.

Correct Pattern:

It("repaginates", func() {
  done := make(chan any)
  go func() {
    defer GinkgoRecover()                 // RULE 1: Protect the suite
    Expect(book.SetFontSize(28)).To(Succeed())
    close(done)
  }()
  Eventually(done).Should(BeClosed())     // RULE 2: Poll, don't block
})

It("repaginates", func() {
  done := make(chan any)
  go func() {
    defer GinkgoRecover()                 // RULE 1
    Expect(book.SetFontSize(28)).To(Succeed())
    close(done)
  }()
  Eventually(done).Should(BeClosed())     // RULE 2: poll, don't block on <-done
})