testclock

Documentation

Overview

Package testclock implements clocks for use in tests.

Index

• Variables
• func GetTags(t clock.Timer) []string
• func HasTags(t clock.Timer, first string, tags ...string) bool
• type FastClock
  • func NewFastClock(now time.Time, ratio int) *FastClock
  • func (f *FastClock) Add(d time.Duration)
  • func (f *FastClock) Close()
  • func (f *FastClock) NewTimer(ctx context.Context) clock.Timer
  • func (f *FastClock) Now() time.Time
  • func (f *FastClock) Set(fNew time.Time)
  • func (f *FastClock) SetTimerCallback(clbk TimerCallback)
  • func (f *FastClock) Sleep(ctx context.Context, d time.Duration) clock.TimerResult
• type TestClock
  • func New(now time.Time) TestClock
  • func UseTime(ctx context.Context, now time.Time) (context.Context, TestClock)
• type TimerCallback

Examples

• FastClock

Variables

var TestRecentTimeLocal = time.Date(2016, time.February, 3, 4, 5, 6, 7, time.Local)

TestRecentTimeLocal is like TestTimeLocal, but in the recent past.

var TestRecentTimeUTC = time.Date(2016, time.February, 3, 4, 5, 6, 7, time.UTC)

TestRecentTimeUTC is like TestTimeUTC, but in the recent past.

var TestTimeLocal = time.Date(1, time.February, 3, 4, 5, 6, 7, time.Local)

TestTimeLocal is an arbitrary time point in the 'Local' time zone for testing.

It corresponds to a negative Unix timestamp, so it might be inappropriate for some tests. Use 'TestRecentTimeLocal' for more "real" test time in this case.

var TestTimeUTC = time.Date(1, time.February, 3, 4, 5, 6, 7, time.UTC)

TestTimeUTC is an arbitrary time point in UTC for testing.

It corresponds to a negative Unix timestamp, so it might be inappropriate for some tests. Use 'TestRecentTimeUTC' for more "real" test time in this case.

Functions

func GetTags

func GetTags(t clock.Timer) []string

GetTags returns the tags associated with the specified timer. If the timer has no tags, an empty slice (nil) will be returned.

func HasTags

func HasTags(t clock.Timer, first string, tags ...string) bool

HasTags tests if a given timer has the same tags.

Types

type FastClock

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

FastClock mimics faster physical clock in tests.

Its API is exactly the same as that of TestClock and can be used in-place. However, unlike TestClock, the time in this clock moves forward as a normal wall clock would, but at an arbitrarily faster rate.

It's useful for integration tests simulating a large system over long period of (wall clock) time where adjusting each indiviudal timeout/delay/timer via testclock API isn't feasible.

Example

// New clock running 1M times faster than wall clock.
clk := NewFastClock(TestRecentTimeUTC, 1000*1000)
defer clk.Close()
ctx := clock.Set(context.Background(), clk)
wallStart := time.Now()
t := clock.NewTimer(ctx)
t.Reset(time.Hour)
<-t.GetC()
if wallTook := time.Since(wallStart); wallTook <= 10*time.Second {
	fmt.Printf("took less than 10 seconds\n")
	

Output:

took less than 10 seconds

func NewFastClock

func NewFastClock(now time.Time, ratio int) *FastClock

NewFastClock creates a new FastClock running faster than a system clock.

You SHOULD call .Close() on the returned object after use to avoid leaks.

func (*FastClock) Add

func (f *FastClock) Add(d time.Duration)

Add advances the test clock's time.

func (*FastClock) Close

func (f *FastClock) Close()

Close frees clock resources.

func (*FastClock) NewTimer

func (f *FastClock) NewTimer(ctx context.Context) clock.Timer

NewTimer creates a new Timer instance, bound to this Clock.

If the supplied Context is canceled, the timer will expire immediately.

func (*FastClock) Now

func (f *FastClock) Now() time.Time

Now returns the current time (see time.Now).

func (*FastClock) Set

func (f *FastClock) Set(fNew time.Time)

Set sets the test clock's time to at least the given time.

Noop if Now() is already after the given time.

func (*FastClock) SetTimerCallback

func (f *FastClock) SetTimerCallback(clbk TimerCallback)

SetTimerCallback is a goroutine-safe method to set an instance-wide callback that is invoked when any timer begins.

func (*FastClock) Sleep

func (f *FastClock) Sleep(ctx context.Context, d time.Duration) clock.TimerResult

Sleep sleeps the current goroutine (see time.Sleep).

Sleep will return a TimerResult containing the time when it was awakened and detailing its execution. If the sleep terminated prematurely from cancellation, the TimerResult's Incomplete() method will return true.

type TestClock

type TestClock interface {
	clock.Clock

	// Set sets the test clock's time.
	Set(time.Time)

	// Add advances the test clock's time.
	Add(time.Duration)

	// SetTimerCallback is a goroutine-safe method to set an instance-wide
	// callback that is invoked when any timer begins.
	SetTimerCallback(TimerCallback)
}

TestClock is a Clock interface with additional methods to help instrument it.

func New

func New(now time.Time) TestClock

New returns a TestClock instance set at the specified time.

func UseTime

func UseTime(ctx context.Context, now time.Time) (context.Context, TestClock)

UseTime instantiates a TestClock and returns a Context that is configured to use that clock, as well as the instantiated clock.

type TimerCallback

type TimerCallback func(time.Duration, clock.Timer)

TimerCallback that can be invoked when a timer has been set. This is useful for sychronizing state when testing.