wait

Documentation

Overview

Package wait provides constructs for waiting on conditionals within specified constraints.

Index

• Variables
• type Constraint
  • func ContinualSuccess(opts ...Option) *Constraint
  • func InitialSuccess(opts ...Option) *Constraint
  • func (c *Constraint) Run() error
• type Option
  • func Attempts(max int) Option
  • func BoolFunc(f func() bool) Option
  • func ErrorFunc(f func() error) Option
  • func Gap(duration time.Duration) Option
  • func TestFunc(f func() (bool, error)) Option
  • func Timeout(duration time.Duration) Option

Variables

var (
	ErrTimeoutExceeded      = errors.New("wait: timeout exceeded")
	ErrAttemptsExceeded     = errors.New("wait: attempts exceeded")
	ErrConditionUnsatisfied = errors.New("wait: condition unsatisfied")
	ErrNoFunction           = errors.New("wait: no function specified")
)

Types

type Constraint

type Constraint struct {
	// contains filtered or unexported fields
}

A Constraint is something a test assertion can wait on before marking the result to be a failure. A Constraint is used in conjunction with either the InitialSuccess or ContinualSuccess option. A call to Run will execute the given function, returning nil or error depending on the Constraint configuration and the results of the function.

InitialSuccess - retry a function until it returns a positive result. If the function never returns a positive result before the Constraint threshold is exceeded, an error is returned from Run().

ContinualSuccess - retry a function asserting it returns a positive result until the Constraint threshold is exceeded. If at any point the function returns a negative result, an error is returned from Run().

A Constraint threshold is configured via either Timeout or Attempts (not both).

Timeout - Constraint is time bound.

Attempts - Constraint is iteration bound.

The use of Gap controls the pace of attempts by setting the amount of time to wait in between each attempt.

func ContinualSuccess

func ContinualSuccess(opts ...Option) *Constraint

ContinualSuccess creates a new Constraint configured by opts that will assert a positive result upon calling Constraint.Run, repeating the call until the Constraint reaches its threshold. If the result is negative, an error is returned from the call to Constraint.Run.

Timeout is used to set the amount of time to assert success. Attempts is used to set the number of iterations to assert success. Gap is used to control the amount of time to wait between iterations.

One of ErrorFunc, BoolFunc, or TestFunc represents the function that will be run under the constraint.

func InitialSuccess

func InitialSuccess(opts ...Option) *Constraint

InitialSuccess creates a new Constraint configured by opts that will wait for a positive result upon calling Constraint.Run. If the threshold of the Constraint is exceeded before reaching a positive result, an error is returned from the call to Constraint.Run.

Timeout is used to set a maximum amount of time to wait for success. Attempts is used to set a maximum number of attempts to wait for success. Gap is used to control the amount of time to wait between retries.

One of ErrorFunc, BoolFunc, or TestFunc represents the function that will be run under the constraint.

func (*Constraint) Run

func (c *Constraint) Run() error

Run the Constraint and produce an error result.

type Option

type Option func(*Constraint)

Option is used to configure a Constraint.

Understood Option functions include Timeout, Attempts, Gap, InitialSuccess, and ContinualSuccess.

func Attempts

func Attempts(max int) Option

Attempts sets an iteration bound on a Constraint.

If set, the Timeout constraint configuration is disabled.

By default a Timeout constraint is set and the Attempts bound is disabled.

func BoolFunc

func BoolFunc(f func() bool) Option

BoolFunc executes f under the thresholds of a Constraint.

func ErrorFunc

func ErrorFunc(f func() error) Option

ErrorFunc will retry f while it returns a non-nil error, or until a wait constraint threshold is exceeded.

func Gap

func Gap(duration time.Duration) Option

Gap sets the amount of time to wait between attempts.

Default 250 milliseconds.

func TestFunc

func TestFunc(f func() (bool, error)) Option

TestFunc will retry f while it returns false, or until a wait constraint threshold is exceeded. If f never succeeds, the latest returned error is wrapped into the result.

func Timeout

func Timeout(duration time.Duration) Option

Timeout sets a time bound on a Constraint.

If set, the Attempts constraint configuration is disabled.

Default 3 seconds.