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 Failer, f func(r *R))
• func RunWith(r Retryer, t Failer, f func(r *R))
• type Counter
  • func ThreeTimes() *Counter
  • func (r *Counter) Continue() bool
• type Failer
• type R
  • func (r *R) Check(err error)
  • func (r *R) Error(args ...interface{})
  • func (r *R) Errorf(format string, args ...interface{})
  • func (r *R) FailNow()
  • func (r *R) Fatal(args ...interface{})
  • func (r *R) Fatalf(format string, args ...interface{})
  • func (r *R) Helper()
  • func (r *R) Log(args ...interface{})
  • func (r *R) Logf(format string, args ...interface{})
  • func (r *R) Stop(err error)
• type Retryer
• type Timer
  • func DefaultFailer() *Timer
  • func TwoSeconds() *Timer
  • func (r *Timer) Continue() bool

Functions

func Run

func Run(t Failer, f func(r *R))

func RunWith

func RunWith(r Retryer, t Failer, 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 Failer

type Failer interface {
	Helper()

	// Log is called for the final test output
	Log(args ...interface{})

	// FailNow is called when the retrying is abandoned.
	FailNow()
}

Failer is an interface compatible with testing.T.

type R

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

R provides context for the retryer.

Logs from Logf, (Error|Fatal)(f) are gathered in an internal buffer and printed only if the retryer fails. Printed logs are deduped and prefixed with source code line numbers

func (*R) Check

func (r *R) Check(err error)

If err is non-nil, equivalent to r.Fatal(err.Error()) followed by r.FailNow(). Otherwise a no-op.

func (*R) Error

func (r *R) Error(args ...interface{})

Error indicates the current run encountered an error and should be retried. It *does not* stop execution of the rest of the run function.

func (*R) Errorf

func (r *R) Errorf(format string, args ...interface{})

Errorf is like Error but allows a format string

func (*R) FailNow

func (r *R) FailNow()

FailNow stops run execution. It is roughly equivalent to:

r.Error("")
return

inside the function being run.

func (*R) Fatal

func (r *R) Fatal(args ...interface{})

Fatal is equivalent to r.Logf(args) followed by r.FailNow(), i.e. the run function should be exited. Retries on the next run are allowed. Fatal is equivalent to

r.Error(args)
return

inside the function being run.

func (*R) Fatalf

func (r *R) Fatalf(format string, args ...interface{})

Fatalf is like Fatal but allows a format string

func (*R) Helper

func (r *R) Helper()

func (*R) Log

func (r *R) Log(args ...interface{})

func (*R) Logf

func (r *R) Logf(format string, args ...interface{})

func (*R) Stop

func (r *R) Stop(err error)

Stop retrying, and fail the test, logging the specified error. Does not stop execution, so return should be called after.

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.

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 DefaultFailer

func DefaultFailer() *Timer

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

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