poll

Documentation

Overview

Package poll provides tools for testing asynchronous code.

Index

• func WaitOn(t TestingT, check func(t LogT) Result, pollOps ...SettingOp)
• type LogT
• type Result
  • func Continue(message string, args ...interface{}) Result
  • func Error(err error) Result
  • func Success() Result
• type SettingOp
  • func WithDelay(delay time.Duration) SettingOp
  • func WithTimeout(timeout time.Duration) SettingOp
• type Settings
• type TestingT

Examples

• SettingOp
• WaitOn

Functions

func WaitOn

func WaitOn(t TestingT, check func(t LogT) Result, pollOps ...SettingOp)

WaitOn a condition or until a timeout. Poll by calling check and exit when check returns a done Result. To fail a test and exit polling with an error return a error result.

Example

package main

import (
	"github.com/pkg/errors"
	"gotest.tools/poll"
)

var t poll.TestingT

func numOfProcesses() (int, error) {
	return 0, nil
}

func main() {
	desired := 10

	check := func(t poll.LogT) poll.Result {
		actual, err := numOfProcesses()
		if err != nil {
			return poll.Error(errors.Wrap(err, "failed to get number of processes"))
		}
		if actual == desired {
			return poll.Success()
		}
		t.Logf("waiting on process count to be %d...", desired)
		return poll.Continue("number of processes is %d, not %d", actual, desired)
	}

	poll.WaitOn(t, check)
}

Types

type LogT

type LogT interface {
	Log(args ...interface{})
	Logf(format string, args ...interface{})
}

LogT is a logging interface that is passed to the WaitOn check function

type Result

type Result interface {
	// Error indicates that the check failed and polling should stop, and the
	// the has failed
	Error() error
	// Done indicates that polling should stop, and the test should proceed
	Done() bool
	// Message provides the most recent state when polling has not completed
	Message() string
}

Result of a check performed by WaitOn

func Continue

func Continue(message string, args ...interface{}) Result

Continue returns a Result that indicates to WaitOn that it should continue polling. The message text will be used as the failure message if the timeout is reached.

func Error

func Error(err error) Result

Error returns a Result that indicates to WaitOn that it should fail the test and stop polling.

func Success

func Success() Result

Success returns a Result where Done() returns true, which indicates to WaitOn that it should stop polling and exit without an error.

type SettingOp

type SettingOp func(config *Settings)

SettingOp is a function which accepts and modifies Settings

Example

package main

import (
	"time"

	"gotest.tools/poll"
)

var t poll.TestingT

func isDesiredState() bool { return false }
func getState() string     { return "" }

func main() {
	check := func(t poll.LogT) poll.Result {
		if isDesiredState() {
			return poll.Success()
		}
		return poll.Continue("state is: %s", getState())
	}
	poll.WaitOn(t, check, poll.WithTimeout(30*time.Second), poll.WithDelay(15*time.Millisecond))
}

func WithDelay

func WithDelay(delay time.Duration) SettingOp

WithDelay sets the delay to wait between polls

func WithTimeout

func WithTimeout(timeout time.Duration) SettingOp

WithTimeout sets the timeout

type Settings

type Settings struct {
	// Timeout is the maximum time to wait for the condition. Defaults to 10s.
	Timeout time.Duration
	// Delay is the time to sleep between checking the condition. Defaults to
	// 100ms.
	Delay time.Duration
}

Settings are used to configure the behaviour of WaitOn

type TestingT

type TestingT interface {
	LogT
	Fatalf(format string, args ...interface{})
}

TestingT is the subset of testing.T used by WaitOn