clock

README

Clock

A wrapper around Go's time package to ease testing.

The sole purpose of this package is to provide a way to test code, using gomock, that uses time functions from Go's time package. While there are ways to get around (e.g. make durations for tickers configurable, so we can override during tests, etc.), it's always better to have more control over time functions like tickers (when the next tick happens), timers (when the timer expires), etc.

NOTE Only the following functions are available:

• Now()
• NewTicker()
• NewTimer()
• Sleep()
• After()
• AfterFunc()
• Tick()

Usage

// mypackage.go
package mypackage

import (
    "fmt"

    "github.com/transcelestial/clock"
)

func MyFunc(c clock.Clock) string {
    return c.Now().Format(time.RFC3339)
}

// mypackage_test.go
package mypackage

import (
    "testing"

    "github.com/transcelestial/clock"

    "github.com/stretchr/testify/assert"
    "github.com/transcelestial/clock/mockclock"
)

func TestMyFunc(t *testing.T) {
    ctrl := gomock.NewController(t)
    // create a mock Clock
    c := mockclock.NewMockClock(ctrl)

    // set some expectations
    now := time.Date(2018, 12, 31, 0, 0, 0, 0, time.UTC)
    c.EXPECT().
		Now().
		Return(now)

    assert.Equal(t, "2018-12-31T00:00:00Z", MyFunc(c))
}

See example_clock_test and example_mockclock_test for more examples.

Alternatives

You may also want to try out these alternatives:

• github.com/benbjohnson/clock
• github.com/thejerf/abtime

Contribute

If you wish to contribute, please use the following guidelines:

• Use conventional commits
• Use effective Go

Documentation

Index

• type Clock
  • func New() Clock
• type Ticker
• type Timer

Types

type Clock

type Clock interface {
	// Now returns the current system time (same as `time.Now()`)
	Now() time.Time
	// NewTicker creates a new ticker that uses the system clock (same as `time.NewTicker()`).
	NewTicker(time.Duration) Ticker
	// NewTimer creates a new timer that uses the system clock (same as `time.NewTimer()`).
	NewTimer(time.Duration) Timer
	// Sleep pauses execution in the current thread for d duration (same as `time.Sleep()`).
	Sleep(time.Duration)
	// After waits for the duration to elapse and then sends the current time
	// on the returned channel (same as `time.After()`).
	After(time.Duration) <-chan time.Time
	// AfterFunc waits for the duration to elapse and then calls f
	// in its own goroutine (same as `time.AfterFunc()`).
	AfterFunc(time.Duration, func()) Timer
	// Tick is a convenience wrapper for NewTicker providing access to the ticking
	// channel only (same as `time.Tick()`).
	Tick(time.Duration) <-chan time.Time
}

func New

func New() Clock

New creates a new system clock

type Ticker

type Ticker interface {
	// C returns the ticker.C chan.
	C() <-chan time.Time
	// Reset resets the ticker to a different duration.
	Reset(d time.Duration)
	// Stop stops the ticker.
	Stop()
}

type Timer

type Timer interface {
	// C returns the timer.C chan.
	C() <-chan time.Time
	// Reset resets the timer to a different duration.
	Reset(d time.Duration)
	// Stop stops the timer.
	Stop() bool
}