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
  • func WithCommand(cmd *cobra.Command) Option
  • func WithResources(p ResourceProvider) Option
  • func WithRootCommand(name string) Option
  • func WithRootFlags(register func(*pflag.FlagSet)) Option
• type Phase
• type Resource
• type ResourceProvider
• 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.

func WithCommand

func WithCommand(cmd *cobra.Command) Option

WithCommand registers an additional subcommand on the testrig root command, for project-specific utilities (e.g. persistent database management). May be passed multiple times.

func WithResources

func WithResources(p ResourceProvider) Option

WithResources registers a provider that supplies isolated infrastructure (e.g. databases) for the run. See ResourceProvider for count semantics and partial-failure behavior.

func WithRootCommand

func WithRootCommand(name string) Option

WithRootCommand sets the CLI name used in help text, examples, and cobra.CommandPath(). Defaults to "testrig" when unset.

func WithRootFlags

func WithRootFlags(register func(*pflag.FlagSet)) Option

WithRootFlags registers persistent flags on the root command, available to every subcommand. Use it to add consumer flags (e.g. --database-url) that a resource provider or custom command reads.

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 Resource

type Resource struct {
	Env             []string
	Reset           func(context.Context) error
	DumpDiagnostics func(ctx context.Context, dir string, iteration int) error
	Cleanup         func() error
}

Resource is one prepared, isolated piece of infrastructure for a test run (most commonly a database). It is the extension point consumers use to plug in setups that need per-worker isolation, reset between diagnose iterations, and post-iteration diagnostics — richer than the shell-style lifecycle hooks.

All fields are optional:

• Env is appended to the child go test environment (e.g. CL_DATABASE_URL=...).
• Reset restores clean state before a diagnose worker is reused.
• DumpDiagnostics writes post-iteration state into the results dir.
• Cleanup tears the resource down once, after the command finishes.

type ResourceProvider

type ResourceProvider func(ctx context.Context, count int) ([]Resource, error)

ResourceProvider supplies count isolated resources for a run. It is called once, before any tests start, with a context that is canceled on SIGINT/SIGTERM.

count is the effective parallel-iteration count for diagnose (one resource per worker, capped by --iterations). For the default root go test invocation and gotestsum, count is always 1 — even when go test uses -p>1, only a single Env slice is applied to the child process.

The provider must return exactly count resources or an error. On error, testrig does not call Cleanup on any returned resources; roll back partial provisioning inside the provider before returning.

type RunOptions

type RunOptions struct {
	GlobalSetup       Hook
	GlobalTeardown    Hook
	IterationSetup    Hook
	IterationTeardown Hook
	ResourceProvider  ResourceProvider
	Commands          []*cobra.Command
	RootFlags         func(*pflag.FlagSet)
	RootCommand       string
}

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 the default go test invocation, gotestsum, and diagnose.
	ScopeGlobal Scope = iota
	// ScopeIteration hooks run only for diagnose iterations.
	ScopeIteration
)