ordering-and-flakes

Ordering and flakes

Two topics that share a root cause: specs that aren't truly independent (ginkgo:overview). Ordering decorators let you declare a dependency on purpose; flake controls let you manage or expose one. Docs: https://onsi.github.io/ginkgo/#serial-specs, https://onsi.github.io/ginkgo/#ordered-containers, https://onsi.github.io/ginkgo/#repeating-spec-runs-and-managing-flaky-specs.

Serial: opt out of parallelism

Serial (container or subject) guarantees a spec never runs in parallel with anything else. Under the hood Ginkgo runs serial specs last, on process #1, after all other processes have exited. Reach for it sparingly. OK for benchmarks, resource hogs, or specs that put an external resource into a known-bad state - but not OK as a band-aid for order-dependence or poorly isolated code/specs.

Describe("Something expensive", Serial, func() {
	It("is a resource hog that can't share the box", func() { ... })
})

→ ginkgo:decorators, ginkgo:parallelism.

Ordered: run specs in definition order

Ordered (container only) guarantees its child specs run sequentially, in written order, on one process — so they may legitimately mutate shared closure state. They can still parallelize against specs in other containers; only the inner order is pinned.

Describe("checking out a book", Ordered, func() {
	var libraryClient *library.Client
	var book *books.Book

	BeforeAll(func() {                         // once, before the first spec
		libraryClient = library.NewClient()
		Expect(libraryClient.Connect()).To(Succeed())
		DeferCleanup(libraryClient.Disconnect) // context-aware: behaves like AfterAll
	})

	It("can fetch a book", func() { book, _ = libraryClient.FetchByTitle("Les Miserables") })
	It("can check it out", func() { Expect(library.CheckOut(book)).To(Succeed()) })
	It("is then out of stock", func() { ... })

	AfterAll(func() { ... })                   // once, after the last spec
})

• BeforeAll/AfterAll are legal only inside an Ordered container (or a container nested within one). That's the whole point of Ordered — once-per-group expensive setup.
• A failing spec skips the rest of the group by default (then AfterAll still runs). Spec independence is gone, so Ginkgo won't pretend the later specs are meaningful.
• ContinueOnFailure (outermost Ordered only — error on a nested container) overrides that: keep running later specs after a failure. Use it when Ordered is just shared setup, not a dependent flow. A failed BeforeAll still skips everything — the setup is presumed broken.
• Nested containers inside an Ordered container are automatically Ordered; there's no way to un-order them.