hooks

Documentation

Overview

Package hooks defines the testrig lifecycle hook interfaces and configuration.

Index

• Variables
• func CatalogNames() []string
• func RegisterPersistentFlags(fs *pflag.FlagSet)
• func RunEntry(ctx context.Context, flags *pflag.FlagSet, opts RunOptions, shellCmd string, ...) error
• func RunGlobalSetup(ctx context.Context, hook Hook) error
• func RunGlobalSetups(ctx context.Context, flags *pflag.FlagSet, opts RunOptions) error
• func RunGlobalTeardown(ctx context.Context, hook Hook) error
• func RunGlobalTeardowns(ctx context.Context, flags *pflag.FlagSet, opts RunOptions) error
• func RunIterationSetup(ctx context.Context, hook Hook) error
• func RunIterationTeardown(ctx context.Context, hook Hook) error
• type Entry
  • func Entries(scope Scope, phase Phase) []Entry
  • func EntryByName(name string) (Entry, bool)
  • func (e Entry) CLIFlag() string
  • func (e Entry) Label() string
• type Hook
  • func BuildIterationHook(opts RunOptions, shell IterationShellCommand, phase Phase) Hook
  • func NewShellHook(cmd string) Hook
• type IterationShellCommand
• type Option
  • func GlobalSetup(h Hook) Option
  • func GlobalTeardown(h Hook) Option
  • func IterationSetup(h Hook) Option
  • func IterationTeardown(h Hook) Option
• type Phase
• type RunOptions
  • func BuildOptions(opts ...Option) RunOptions
  • func (o RunOptions) Hook(name string) Hook
• type RunOrder
• type Scope

Variables

var Catalog = []Entry{
	{
		Name:      "GlobalSetup",
		Flag:      "global-setup",
		Scope:     ScopeGlobal,
		Phase:     PhaseSetup,
		FlagUsage: "Shell command to run before tests",
	},
	{
		Name:      "GlobalTeardown",
		Flag:      "global-teardown",
		Scope:     ScopeGlobal,
		Phase:     PhaseTeardown,
		FlagUsage: "Shell command to run after tests",
	},
	{
		Name:      "IterationSetup",
		Flag:      "iteration-setup",
		Scope:     ScopeIteration,
		Phase:     PhaseSetup,
		FlagUsage: "Shell command to run before each diagnose iteration",
	},
	{
		Name:      "IterationTeardown",
		Flag:      "iteration-teardown",
		Scope:     ScopeIteration,
		Phase:     PhaseTeardown,
		FlagUsage: "Shell command to run after each diagnose iteration",
	},
}

Catalog is the single source of truth for lifecycle hooks. Add an Entry here to get a CLI flag, config binding (iteration scope), and docs row (via go generate).

Functions

func CatalogNames

func CatalogNames() []string

CatalogNames returns Option registrar names in catalog order.

func RegisterPersistentFlags

func RegisterPersistentFlags(fs *pflag.FlagSet)

RegisterPersistentFlags adds every catalog entry as a root persistent string flag.

func RunEntry

func RunEntry(
	ctx context.Context,
	flags *pflag.FlagSet,
	opts RunOptions,
	shellCmd string,
	e Entry,
	order RunOrder,
) error

RunEntry runs native and/or shell hooks for one catalog entry.

func RunGlobalSetup

func RunGlobalSetup(ctx context.Context, hook Hook) error

RunGlobalSetup runs hook before tests execute. A nil hook is a no-op.

func RunGlobalSetups

func RunGlobalSetups(ctx context.Context, flags *pflag.FlagSet, opts RunOptions) error

RunGlobalSetups runs all global setup hooks (native then shell per entry).

func RunGlobalTeardown

func RunGlobalTeardown(ctx context.Context, hook Hook) error

RunGlobalTeardown runs hook after tests execute. A nil hook is a no-op.

func RunGlobalTeardowns

func RunGlobalTeardowns(ctx context.Context, flags *pflag.FlagSet, opts RunOptions) error

RunGlobalTeardowns runs all global teardown hooks (shell then native per entry).

func RunIterationSetup

func RunIterationSetup(ctx context.Context, hook Hook) error

RunIterationSetup runs hook before a single diagnose iteration. A nil hook is a no-op.

func RunIterationTeardown

func RunIterationTeardown(ctx context.Context, hook Hook) error

RunIterationTeardown runs hook after a single diagnose iteration. A nil hook is a no-op.

Types

type Entry

type Entry struct {
	Name      string // e.g. GlobalSetup; matches testrig.GlobalSetup and RunOptions field.
	Flag      string // e.g. global-setup (persistent root flag, no leading dashes).
	Scope     Scope
	Phase     Phase
	FlagUsage string // Cobra flag description.
}

Entry describes one lifecycle hook in the catalog: public Option name, CLI flag, and scope.

func Entries

func Entries(scope Scope, phase Phase) []Entry

Entries returns catalog entries matching scope and phase, in catalog order.

func EntryByName

func EntryByName(name string) (Entry, bool)

EntryByName returns a catalog entry by Option/func name.

func (Entry) CLIFlag

func (e Entry) CLIFlag() string

CLIFlag returns the flag with leading dashes.

func (Entry) Label

func (e Entry) Label() string

Label returns a short phrase for error messages (e.g. "global setup").

type Hook

type Hook func(context.Context) error

Hook is a lifecycle callback. The context carries cancellation from the test runner — hooks should respect it for long-running operations.

func BuildIterationHook

func BuildIterationHook(opts RunOptions, shell IterationShellCommand, phase Phase) Hook

BuildIterationHook composes iteration setup or teardown hooks for diagnose. Returns nil when no native or shell hooks are configured for that phase.

func NewShellHook

func NewShellHook(cmd string) Hook

NewShellHook returns a Hook that runs cmd via the system shell (sh -c). The hook respects context cancellation. On non-zero exit, the combined stdout+stderr is included in the returned error so failing setup commands are diagnosable.

type IterationShellCommand

type IterationShellCommand func(flag string) string

IterationShellCommand resolves a shell command for an iteration-scoped entry from flag values.

type Option

type Option func(*runnerOptions)

Option configures the testrig CLI runner.

func GlobalSetup

func GlobalSetup(h Hook) Option

GlobalSetup registers a hook to run once before any tests.

func GlobalTeardown

func GlobalTeardown(h Hook) Option

GlobalTeardown registers a hook to run once after all tests finish.

func IterationSetup

func IterationSetup(h Hook) Option

IterationSetup registers a hook to run before each diagnose iteration.

func IterationTeardown

func IterationTeardown(h Hook) Option

IterationTeardown registers a hook to run after each diagnose iteration.

type Phase

type Phase uint8

Phase is whether the hook runs before or after its scope's work.

const (
	// PhaseSetup hooks run before the scope's work.
	PhaseSetup Phase = iota
	// PhaseTeardown hooks run after the scope's work.
	PhaseTeardown
)

type RunOptions

type RunOptions struct {
	GlobalSetup       Hook
	GlobalTeardown    Hook
	IterationSetup    Hook
	IterationTeardown Hook
}

RunOptions contains the evaluated configuration for the testrig CLI. It is exported for internal use by the CLI engine.

func BuildOptions

func BuildOptions(opts ...Option) RunOptions

BuildOptions evaluates the functional options and returns the internal struct. It is exported for internal use by the CLI engine.

func (RunOptions) Hook

func (o RunOptions) Hook(name string) Hook

Hook returns the native hook registered for name, or nil.

type RunOrder

type RunOrder uint8

RunOrder controls native vs shell hook execution for one catalog entry.

const (
	// NativeThenShell runs the Go hook before the shell flag command.
	NativeThenShell RunOrder = iota
	// ShellThenNative runs the shell flag command before the Go hook.
	ShellThenNative
)

type Scope

type Scope uint8

Scope is when a hook runs relative to testrig subcommands.

const (
	// ScopeGlobal hooks run for run, gotestsum, and diagnose.
	ScopeGlobal Scope = iota
	// ScopeIteration hooks run only for diagnose iterations.
	ScopeIteration
)