retry

Documentation

Overview

Package retry provides support for repeating operations in tests.

A sample retry operation looks like this:

func TestX(t *testing.T) {
    retry.Run(t, func(r *retry.R) {
        if err := foo(); err != nil {
			r.Errorf("foo: %s", err)
			return
        }
    })
}

Run uses the DefaultFailer, which is a Timer with a Timeout of 7s, and a Wait of 25ms. To customize, use RunWith.

WARNING: unlike *testing.T, *retry.R#Fatal and FailNow *do not* fail the test function entirely, only the current run the retry func

Index

• func Run(t TestingTB, f func(r *R), opts ...Option)
• func RunWith(r Retryer, t TestingTB, f func(r *R))
• type Counter
  • func ThreeTimes() *Counter
  • func (r *Counter) Continue() bool
• type Option
  • func WithFullOutput() Option
  • func WithImmediateCleanup() Option
  • func WithRetryer(retryer Retryer) Option
• type R
  • func (r *R) Check(err error)
  • func (r *R) Cleanup(clean func())
  • func (r *R) Error(args ...any)
  • func (r *R) Errorf(format string, args ...any)
  • func (r *R) Fail()
  • func (r *R) FailNow()
  • func (r *R) Failed() bool
  • func (r *R) Fatal(args ...any)
  • func (r *R) Fatalf(format string, args ...any)
  • func (r *R) Helper()
  • func (r *R) Log(args ...any)
  • func (r *R) Logf(format string, args ...any)
  • func (r *R) Name() string
  • func (r *R) Setenv(key, value string)
  • func (r *R) Stop(err error)
  • func (r *R) TempDir() string
• type Retryer
  • func DefaultRetryer() Retryer
• type TestingTB
• type Timer
  • func ThirtySeconds() *Timer
  • func TwoSeconds() *Timer
  • func (r *Timer) Continue() bool

Functions

func Run

func Run(t TestingTB, f func(r *R), opts ...Option)

func RunWith

func RunWith(r Retryer, t TestingTB, f func(r *R))

Types

type Counter

type Counter struct {
	Count int
	Wait  time.Duration
	// contains filtered or unexported fields
}

Counter repeats an operation a given number of times and waits between subsequent operations.

func ThreeTimes

func ThreeTimes() *Counter

ThreeTimes repeats an operation three times and waits 25ms in between.

func (*Counter) Continue

func (r *Counter) Continue() bool

type Option

type Option func(r *R)

func WithFullOutput

func WithFullOutput() Option

func WithImmediateCleanup

func WithImmediateCleanup() Option

WithImmediateCleanup will cause all cleanup operations added by calling the Cleanup method on *R to be performed after the retry attempt completes (regardless of pass/fail status) Use this only if all resources created during the retry loop should not persist after the retry has finished.

func WithRetryer

func WithRetryer(retryer Retryer) Option

type R

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

func (*R) Check

func (r *R) Check(err error)

Check will call r.Fatal(err) if err is not nil

func (*R) Cleanup

func (r *R) Cleanup(clean func())

func (*R) Error

func (r *R) Error(args ...any)

func (*R) Errorf

func (r *R) Errorf(format string, args ...any)

func (*R) Fail

func (r *R) Fail()

func (*R) FailNow

func (r *R) FailNow()

func (*R) Failed

func (r *R) Failed() bool

func (*R) Fatal

func (r *R) Fatal(args ...any)

func (*R) Fatalf

func (r *R) Fatalf(format string, args ...any)

func (*R) Helper

func (r *R) Helper()

func (*R) Log

func (r *R) Log(args ...any)

func (*R) Logf

func (r *R) Logf(format string, args ...any)

func (*R) Name

func (r *R) Name() string

Name will return the name of the underlying TestingT.

func (*R) Setenv

func (r *R) Setenv(key, value string)

Setenv will save the current value of the specified env var, set it to the specified value and then restore it to the original value in a cleanup function once the retry attempt has finished.

func (*R) Stop

func (r *R) Stop(err error)

func (*R) TempDir

func (r *R) TempDir() string

TempDir will use the wrapped TestingT to create a temporary directory that will be cleaned up when ALL RETRYING has finished.

type Retryer

type Retryer interface {
	// Continue returns true if the operation should be repeated, otherwise it
	// returns false to indicate retrying should stop.
	Continue() bool
}

Retryer provides an interface for repeating operations until they succeed or an exit condition is met.

func DefaultRetryer

func DefaultRetryer() Retryer

DefaultRetryer provides default retry.Run() behavior for unit tests, namely 7s timeout with a wait of 25ms

type TestingTB

type TestingTB interface {
	Cleanup(func())
	Error(args ...any)
	Errorf(format string, args ...any)
	Fail()
	FailNow()
	Failed() bool
	Fatal(args ...any)
	Fatalf(format string, args ...any)
	Helper()
	Log(args ...any)
	Logf(format string, args ...any)
	Name() string
	Setenv(key, value string)
	TempDir() string
}

TestingTB is an interface that describes the implementation of the testing object. Using an interface that describes testing.TB instead of the actual implementation makes testutil usable in a wider variety of contexts (e.g. use with ginkgo : https://godoc.org/github.com/onsi/ginkgo#GinkgoT)

type Timer

type Timer struct {
	Timeout time.Duration
	Wait    time.Duration
	// contains filtered or unexported fields
}

Timer repeats an operation for a given amount of time and waits between subsequent operations.

func ThirtySeconds

func ThirtySeconds() *Timer

ThirtySeconds repeats an operation for thirty seconds and waits 500ms in between. Best for known slower operations like waiting on eventually consistent state.

func TwoSeconds

func TwoSeconds() *Timer

TwoSeconds repeats an operation for two seconds and waits 25ms in between.

func (*Timer) Continue

func (r *Timer) Continue() bool