clock

README

clock

Time utility with lovely mocking support.

This is essentially a replacement for the time package which allows you to seamlessly swap in mock times, timers, and tickers. See the godocs (link above) for more detailed usage.

Example

hello.go

package main

import (
    "fmt"
    "github.com/WatchBeam/clock"
)

func main() {
    fmt.Printf("the time is %s", displayer{clock.C}.formatted())
}

type displayer struct {
    c clock.Clock
}

func (d displayer) formatted() string {
    now := d.c.Now()
    return fmt.Sprintf("%d:%d:%d", now.Hour(), now.Minute(), now.Second())
}

hello_test.go

package main

import (
    "testing"
    "time"

    "github.com/WatchBeam/clock"
    "github.com/stretchr/testify/assert"
)

func TestDisplaysCorrectly(t *testing.T) {
    date, _ := time.Parse(time.UnixDate, "Sat Mar  7 11:12:39 PST 2015")
    c := clock.NewMockClock(date)
    d := displayer{c}

    assert.Equal(t, "11:12:39", d.formatted())
    c.AddTime(42 * time.Second)
    assert.Equal(t, "11:13:21", d.formatted())
}

API & Compatibility

The API provided by this package and the mock version is nearly identical to that of the time package, with two notable differences:

• The channel for Ticker and Timer instances is accessed via the .Chan() method, rather than reading the .C property. This allows the structures to be swapped out for their mock variants.
• The mock Ticker never skips ticks when time advances. This allows you to call .AddTime/.SetTime on the mock clock without having to advance to each "ticked" time.

Documentation

Index

• Variables
• type Clock
• type DefaultClock
  • func (dc DefaultClock) After(d time.Duration) <-chan time.Time
  • func (dc DefaultClock) AfterFunc(d time.Duration, f func()) Timer
  • func (dc DefaultClock) NewTicker(d time.Duration) Ticker
  • func (dc DefaultClock) NewTimer(d time.Duration) Timer
  • func (dc DefaultClock) Now() time.Time
  • func (dc DefaultClock) Since(t time.Time) time.Duration
  • func (dc DefaultClock) Sleep(d time.Duration)
  • func (dc DefaultClock) Tick(d time.Duration) <-chan time.Time
• type MockClock
  • func NewMockClock(start ...time.Time) *MockClock
  • func (m *MockClock) AddTime(d time.Duration)
  • func (m *MockClock) After(d time.Duration) <-chan time.Time
  • func (m *MockClock) AfterFunc(d time.Duration, f func()) Timer
  • func (m *MockClock) NewTicker(d time.Duration) Ticker
  • func (m *MockClock) NewTimer(d time.Duration) Timer
  • func (m *MockClock) Now() time.Time
  • func (m *MockClock) SetTime(t time.Time)
  • func (m *MockClock) Since(t time.Time) time.Duration
  • func (m *MockClock) Sleep(d time.Duration)
  • func (m *MockClock) Tick(d time.Duration) <-chan time.Time
• type Ticker
  • func NewMockTicker(c Clock, interval time.Duration) Ticker
• type Timer
  • func NewMockTimer(c Clock) Timer

Variables

var C = DefaultClock{}

C holds a default clock that uses time.Now as its time source. This is what you should normally use in your code.

Types

type Clock

type Clock interface {
	Now() time.Time
	After(d time.Duration) <-chan time.Time
	Sleep(d time.Duration)
	Tick(d time.Duration) <-chan time.Time
	AfterFunc(d time.Duration, f func()) Timer
	NewTimer(d time.Duration) Timer
	NewTicker(d time.Duration) Ticker
	Since(t time.Time) time.Duration
}

The Clock interface provides time-based functionality. It should be used rather than the `time` package in situations where you want to mock things.

type DefaultClock

type DefaultClock struct{}

DefaultClock is an implementation of the Clock interface that uses standard time methods.

func (DefaultClock) After

func (dc DefaultClock) After(d time.Duration) <-chan time.Time

After waits for the duration to elapse and then sends the current time on the returned channel.

func (DefaultClock) AfterFunc

func (dc DefaultClock) AfterFunc(d time.Duration, f func()) Timer

AfterFunc waits for the duration to elapse and then calls f in its own goroutine. It returns a Timer that can be used to cancel the call using its Stop method.

func (DefaultClock) NewTicker

func (dc DefaultClock) NewTicker(d time.Duration) Ticker

NewTicker returns a new Ticker containing a channel that will send the time with a period specified by the duration argument.

func (DefaultClock) NewTimer

func (dc DefaultClock) NewTimer(d time.Duration) Timer

NewTimer creates a new Timer that will send the current time on its channel after at least duration d.

func (DefaultClock) Now

func (dc DefaultClock) Now() time.Time

Now returns the current local time.

func (DefaultClock) Since

func (dc DefaultClock) Since(t time.Time) time.Duration

Since returns the time elapsed since t.

func (DefaultClock) Sleep

func (dc DefaultClock) Sleep(d time.Duration)

Sleep pauses the current goroutine for at least the duration d. A negative or zero duration causes Sleep to return immediately.

func (DefaultClock) Tick

func (dc DefaultClock) Tick(d time.Duration) <-chan time.Time

Tick is a convenience wrapper for NewTicker providing access to the ticking channel only. While Tick is useful for clients that have no need to shut down the Ticker, be aware that without a way to shut it down the underlying Ticker cannot be recovered by the garbage collector; it "leaks".

type MockClock

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

MockClock provides a Clock whose time only changes or advances when manually specified to do so. This is useful for unit tests.

func NewMockClock

func NewMockClock(start ...time.Time) *MockClock

NewMockClock creates a new mock clock, with its current time set to the provided optional start time.

func (*MockClock) AddTime

func (m *MockClock) AddTime(d time.Duration)

AddTime adds the given time duration to the clock.

func (*MockClock) After

func (m *MockClock) After(d time.Duration) <-chan time.Time

After waits for the duration to elapse and then sends the current time on the returned channel.

func (*MockClock) AfterFunc

func (m *MockClock) AfterFunc(d time.Duration, f func()) Timer

AfterFunc waits for the duration to elapse and then calls f in its own goroutine. It returns a Timer that can be used to cancel the call using its Stop method.

func (*MockClock) NewTicker

func (m *MockClock) NewTicker(d time.Duration) Ticker

NewTicker returns a new mock Ticker containing a channel that will send the time with a period specified by the duration argument. Note: unlike the default ticker included in Go, the mock ticker will *never* skip ticks as time advances.

func (*MockClock) NewTimer

func (m *MockClock) NewTimer(d time.Duration) Timer

NewTimer creates a new mock Timer that will send the current time on its channel after at least duration d.

func (*MockClock) Now

func (m *MockClock) Now() time.Time

Now returns the current local time.

func (*MockClock) SetTime

func (m *MockClock) SetTime(t time.Time)

SetTime sets the mock clock's time to the given absolute time.

func (*MockClock) Since

func (m *MockClock) Since(t time.Time) time.Duration

Since returns the time elapsed since t.

func (*MockClock) Sleep

func (m *MockClock) Sleep(d time.Duration)

Sleep pauses the current goroutine for at least the duration d. A negative or zero duration causes Sleep to return immediately.

func (*MockClock) Tick

func (m *MockClock) Tick(d time.Duration) <-chan time.Time

Tick is a convenience wrapper for NewTicker providing access to the ticking channel only. While Tick is useful for clients that have no need to shut down the Ticker, be aware that without a way to shut it down the underlying Ticker cannot be recovered by the garbage collector; it "leaks".

type Ticker

type Ticker interface {
	Chan() <-chan time.Time
	Stop()
}

The Ticker is an interface for time.Ticker, and can also be swapped in mocks. This *does* change its API so that it can fit into an interface -- rather than using the channel at .C, you should call Chan() and use the returned channel just as you would .C.

func NewMockTicker

func NewMockTicker(c Clock, interval time.Duration) Ticker

NewMockTicker creates a new Ticker using the provided Clock. You should not use this directly outside of unit tests; use Clock.NewTicker().

type Timer

type Timer interface {
	Chan() <-chan time.Time
	Reset(d time.Duration) bool
	Stop() bool
}

The Timer is an interface for time.Timer, and can also be swapped in mocks. This *does* change its API so that it can fit into an interface -- rather than using the channel at .C, you should call Chan() and use the returned channel just as you would .C.

func NewMockTimer

func NewMockTimer(c Clock) Timer

NewMockTimer creates a new Timer using the provided Clock. You should not use this directly outside of unit tests; use Clock.NewTimer().