clock

README

clock

Package clock provides an abstraction for system time that enables testing of time-sensitive code.

Where you'd use time.Now, instead use clk.Now where clk is an instance of clock.Clock.

When running your code in production, pass it a Clock given by clock.Default() and when you're running it in your tests, pass it an instance of Clock from NewFake().

When you do that, you can use FakeClock's Add and Set methods to control how time behaves in your tests. That makes the tests you'll write more reliable while also expanding the space of problems you can test.

This code intentionally does not attempt to provide an abstraction over time.Ticker and time.Timer because Go does not have the runtime or API hooks available to do so reliably. See https://github.com/golang/go/issues/8869

As with any use of time, be sure to test Time equality with time.Time#Equal, not ==.

For API documentation, see the godoc.

Documentation

Overview

Package clock provides an abstraction for system time that enables testing of time-sensitive code.

Where you'd use time.Now, instead use clk.Now where clk is an instance of Clock.

When running your code in production, pass it a Clock given by clock.Default() and when you're running it in your tests, pass it an instance of Clock from NewFake().

When you do that, you can use FakeClock's Add and Set methods to control how time behaves in your tests. That makes the tests you'll write more reliable while also expanding the space of problems you can test.

This code intentionally does not attempt to provide an abstraction over time.Ticker and time.Timer because Go does not have the runtime or API hooks available to do so reliably. See https://github.com/golang/go/issues/8869

Index

• type Clock
  • func Default() Clock
  • func New() Clock
• type FakeClock
  • func NewFake() FakeClock
• type Timer
  • func (t *Timer) Reset(d time.Duration) bool
  • func (t *Timer) Stop() bool

Examples

• Clock
• FakeClock

Types

type Clock

type Clock interface {
	// Now returns the Clock's current view of the time. Mutating the
	// returned Time will not mutate the clock's time.
	Now() time.Time

	// Sleep causes the current goroutine to sleep for the given duration.
	Sleep(time.Duration)

	// After returns a channel that fires after the given duration.
	After(time.Duration) <-chan time.Time

	// Since is a short hand for Now().Sub(t).
	Since(time.Time) time.Duration

	// NewTimer makes a Timer based on this clock's time. Using Timers and
	// negative durations in the Clock or Timer API is undefined behavior and
	// may be changed.
	NewTimer(time.Duration) *Timer
}

Clock is an abstraction over system time. New instances of it can be made with Default and NewFake.

Example

c := New()
now := c.Now()
fmt.Println(now.UTC().Zone())

Output:

UTC 0

func Default

func Default() Clock

Deprecated: Default is just an alias for New but less memorable.

func New

func New() Clock

New returns a Clock that matches the actual system time.

type FakeClock

type FakeClock interface {
	Clock
	// Adjust the time that will be returned by Now.
	Add(d time.Duration)

	// Set the Clock's time to exactly the time given.
	Set(t time.Time)
}

FakeClock is a Clock with additional controls. The return value of Now return can be modified with Add. Use NewFake to get a thread-safe FakeClock implementation.

Example

c := New()
fc := NewFake()
fc.Add(20 * time.Hour)
fc.Add(-5 * time.Minute) // negatives work, as well

if fc.Now().Equal(fc.Now()) {
	fmt.Println("FakeClocks' Times always equal themselves.")
}
if !c.Now().Equal(fc.Now()) {
	fmt.Println("Clock and FakeClock can be set to different times.")
}
if !fc.Now().Equal(NewFake().Now()) {
	fmt.Println("FakeClocks work independently, too.")
}

Output:

FakeClocks' Times always equal themselves.
Clock and FakeClock can be set to different times.
FakeClocks work independently, too.

func NewFake

func NewFake() FakeClock

NewFake returns a FakeClock to be used in tests that need to manipulate time. Its initial value is always the unix epoch in the UTC timezone. The FakeClock returned is thread-safe.

type Timer

type Timer struct {
	C <-chan time.Time
	// contains filtered or unexported fields
}

func (*Timer) Reset

func (t *Timer) Reset(d time.Duration) bool

func (*Timer) Stop

func (t *Timer) Stop() bool