Decorators modify the behavior of container nodes, subject nodes, and setup/teardown nodes. They control execution order, timeouts, retries, labeling, and more.
Adds labels to specs or containers for filtering and organization.
func Label(labels ...string) Labels
type Labels []stringParameters:
labels: One or more label stringsExample:
Describe("API Tests", Label("integration", "api"), func() {
It("handles GET requests", Label("smoke"), func() {
// test code
})
It("handles POST requests", Label("slow"), func() {
// test code
})
})
// Run with: ginkgo --label-filter="integration && !slow"Adds semantic version constraints to specs or containers.
func SemVerConstraint(constraints ...string) SemVerConstraints
type SemVerConstraints []stringParameters:
constraints: Semantic version constraint expressions (e.g., ">=1.0.0", "<2.0.0")Example:
Describe("Version-specific tests", func() {
It("works in v1.x", SemVerConstraint(">=1.0.0", "<2.0.0"), func() {
// test code
})
It("works in v2.x", SemVerConstraint(">=2.0.0"), func() {
// test code
})
})
// Run with: ginkgo --sem-ver-filter="1.5.0"Retries a failed spec up to N times. If any attempt passes, the spec passes.
func FlakeAttempts(attempts uint) FlakeAttempts
type FlakeAttempts uintParameters:
attempts: Maximum number of retry attemptsExample:
It("handles flaky external API", FlakeAttempts(3), func() {
// This will retry up to 3 times on failure
response := callExternalAPI()
Expect(response.Status).To(Equal(200))
})Requires a spec to pass N times consecutively. If any run fails, the spec fails.
func MustPassRepeatedly(count uint) MustPassRepeatedly
type MustPassRepeatedly uintParameters:
count: Number of times the spec must passExample:
It("is consistently stable", MustPassRepeatedly(5), func() {
// Must pass 5 times in a row
result := performOperation()
Expect(result).To(BeTrue())
})Sets a timeout for an individual node (BeforeEach, It, AfterEach, etc.).
func NodeTimeout(timeout time.Duration) NodeTimeout
type NodeTimeout time.DurationParameters:
timeout: Maximum duration for the nodeExample:
BeforeEach(func(ctx SpecContext) {
// This BeforeEach has 5 second timeout
setupResources(ctx)
}, NodeTimeout(5*time.Second))
It("completes quickly", func() {
// test code
}, NodeTimeout(2*time.Second))Sets a timeout for an entire spec (including all BeforeEach, It, and AfterEach nodes).
func SpecTimeout(timeout time.Duration) SpecTimeout
type SpecTimeout time.DurationParameters:
timeout: Maximum duration for the entire specExample:
It("performs end-to-end test", func(ctx SpecContext) {
By("starting services")
startServices(ctx)
By("running test")
runTest(ctx)
By("checking results")
checkResults(ctx)
}, SpecTimeout(30*time.Second))Sets the grace period for cleanup after an interrupt or timeout.
func GracePeriod(gracePeriod time.Duration) GracePeriod
type GracePeriod time.DurationParameters:
gracePeriod: Duration to allow for cleanupExample:
It("cleans up gracefully", func(ctx SpecContext) {
resource := allocateExpensiveResource()
DeferCleanup(func() {
resource.Cleanup()
})
performLongOperation(ctx)
}, SpecTimeout(10*time.Second), GracePeriod(5*time.Second))Marks a container so its specs run sequentially in order, not randomized.
const OrderedExample:
Describe("Sequential workflow", Ordered, func() {
var workflowID string
It("creates workflow", func() {
workflowID = createWorkflow()
})
It("starts workflow", func() {
startWorkflow(workflowID)
})
It("completes workflow", func() {
Eventually(func() bool {
return isWorkflowComplete(workflowID)
}).Should(BeTrue())
})
})Marks specs to never run in parallel, even when running with -p flag.
const SerialExample:
Describe("Database tests", Serial, func() {
// These tests modify shared state and must run serially
It("migrates schema", func() {
migrateSchema()
})
It("seeds data", func() {
seedTestData()
})
})In an Ordered container, continue running subsequent specs even if one fails.
const ContinueOnFailureExample:
Describe("Test suite", Ordered, ContinueOnFailure, func() {
It("test 1", func() {
Expect(false).To(BeTrue()) // Fails
})
It("test 2", func() {
// Still runs despite test 1 failure
Expect(true).To(BeTrue())
})
})Focuses on specific specs or containers. Only focused specs run.
const FocusExample:
Describe("Feature tests", func() {
It("test 1", func() {
// Will not run
})
It("test 2", Focus, func() {
// Only this runs
})
})
// Equivalent to:
FIt("test 2", func() {
// Only this runs
})Marks specs or containers as pending (skipped).
const PendingExample:
Describe("Future feature", Pending, func() {
It("will be implemented later", func() {
// Not run
})
})
// Equivalent to:
PIt("will be implemented later", func() {
// Not run
})For setup nodes in an Ordered container, run once per ordered context instead of per spec.
const OncePerOrderedExample:
Describe("Ordered tests", Ordered, func() {
BeforeEach(func() {
// Normally runs before each It
// With OncePerOrdered, runs once at start
setupExpensiveResource()
}, OncePerOrdered)
It("test 1", func() {
useResource()
})
It("test 2", func() {
useResource()
})
})Emits progress reports if a node hasn't completed after the specified duration.
func PollProgressAfter(interval time.Duration) PollProgressAfter
type PollProgressAfter time.DurationParameters:
interval: Duration after which to start emitting progressExample:
It("performs long operation", func() {
// Emit progress if not done after 5 seconds
performLongOperation()
}, PollProgressAfter(5*time.Second))Sets the rate at which to emit progress reports after PollProgressAfter has elapsed.
func PollProgressInterval(interval time.Duration) PollProgressInterval
type PollProgressInterval time.DurationParameters:
interval: Rate for emitting progress reportsExample:
It("monitors progress", func() {
performLongOperation()
}, PollProgressAfter(5*time.Second), PollProgressInterval(2*time.Second))Disables progress reporting for a node.
const SuppressProgressReportingExample:
It("runs without progress reports", func() {
performOperation()
}, SuppressProgressReporting)Adjusts the reported source code location for failures.
func Offset(offset int) Offset
type Offset intParameters:
offset: Number of stack frames to skip (positive) or add (negative)Example:
func CustomAssertion(value string) {
// Report failures at caller's location, not here
It("validates value", Offset(1), func() {
Expect(value).To(BeValid())
})
}Explicitly sets the code location for a node.
func CodeLocation(cl CodeLocation) CodeLocation
type CodeLocation struct {
FileName string
LineNumber int
FullStackTrace string
}Methods:
func (cl CodeLocation) String() string
func (cl CodeLocation) ContentsOfLine() stringExample:
loc := types.NewCodeLocation(2) // Get location 2 frames up
It("has custom location", CodeLocation(loc), func() {
// test code
})Sets execution priority for specs. Higher priority specs run first.
func SpecPriority(priority int) SpecPriority
type SpecPriority intParameters:
priority: Integer priority (higher = runs first)Example:
Describe("Tests", func() {
It("low priority", SpecPriority(1), func() {
// Runs last
})
It("high priority", SpecPriority(10), func() {
// Runs first
})
It("medium priority", SpecPriority(5), func() {
// Runs second
})
})Advanced decorator that wraps node execution, allowing custom behavior before and after.
func AroundNode[F types.AroundNodeAllowedFuncs](f F) types.AroundNodeDecorator
// AroundNodeAllowedFuncs are function signatures allowed for AroundNode
type AroundNodeAllowedFuncs interface {
func(ctx context.Context, fn func(ctx context.Context))
func(ctx context.Context, fn func(ctx context.Context) error) error
func(fn func())
func(fn func() error) error
}Example:
// Add tracing around each It
var _ = It("is traced", AroundNode(func(ctx context.Context, fn func(ctx context.Context)) {
span := startTracing("test-span")
defer span.Finish()
fn(ctx) // Run the actual test
}), func(ctx context.Context) {
// Test code runs here
performOperation()
})Decorators can be combined to create sophisticated test behaviors:
Describe("Complex test scenarios", func() {
It("handles everything",
Label("integration", "slow"),
FlakeAttempts(3),
SpecTimeout(30*time.Second),
PollProgressAfter(10*time.Second),
func(ctx SpecContext) {
// Test implementation
})
})Most decorators work on both individual specs and containers:
Describe("Feature", Label("feature"), Serial, func() {
// All specs inherit Label and Serial
BeforeEach(func() {
setupData()
}, NodeTimeout(5*time.Second))
It("test 1", func() {
// Inherits Label and Serial from Describe
})
It("test 2", Label("smoke"), func() {
// Has both "feature" and "smoke" labels
})
})