package poll

import "gotest.tools/v3/poll"

Package poll provides tools for testing asynchronous code.

Index ¶

• func WaitOn(t TestingT, check Check, pollOps ...SettingOp)
• type Check
• func Connection(network, address string) Check
• func FileExists(path string) Check
• type LogT
• type Result
• func Compare(compare cmp.Comparison) 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 Check, 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.

package main

import (
	"fmt"

	"gotest.tools/v3/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(fmt.Errorf("failed to get number of processes: %w", err))
		}
		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 Check ¶

type Check func(t LogT) Result

Check is a function which will be used as check for the WaitOn method.

func Connection ¶

func Connection(network, address string) Check

Connection try to open a connection to the address on the named network. See net.Dial for a description of the network and address parameters.

func FileExists ¶

func FileExists(path string) Check

FileExists looks on filesystem and check that path exists.

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 Compare ¶

func Compare(compare cmp.Comparison) Result

Compare values using the cmp.Comparison. If the comparison fails return a result which indicates to WaitOn that it should continue waiting. If the comparison is successful then WaitOn stops polling.

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

package main

import (
	"time"

	"gotest.tools/v3/poll"
)

var t poll.TestingT

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

func main() {
	check := func(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

Source Files ¶

check.go poll.go