clock

README

clock

Clock is a small library for mocking time in Go. It provides an interface around the standard library's time package so that the application can use the realtime clock while tests can use the mock clock.

Usage

Realtime Clock

Your application can maintain a Clock variable that will allow realtime and mock clocks to be interchangeable. For example, if you had an Application type:

import "github.com/0xgirish/clock"

type Application struct {
	Clock clock.Clock
}

You could initialize it to use the realtime clock like this:

var app Application
app.Clock = clock.New()
...

Then all timers and time-related functionality should be performed from the Clock variable.

Mocking time

In your tests, you will want to use a Mock clock:

import (
	"testing"

	"github.com/0xgirish/clock"
)

func TestApplication_DoSomething(t *testing.T) {
	mock := clock.NewMock()
	app := Application{Clock: mock}
	...
}

Now that you've initialized your application to use the mock clock, you can adjust the time programmatically. The mock clock always starts from the Unix epoch (midnight UTC on Jan 1, 1970).

Controlling time

The mock clock provides the same functions that the standard library's time package provides. For example, to find the current time, you use the Now() function:

mock := clock.NewMock()

// Find the current time.
mock.Now().UTC() // 1970-01-01 00:00:00 +0000 UTC

// Move the clock forward.
mock.Add(2 * time.Hour)

// Check the time again. It's 2 hours later!
mock.Now().UTC() // 1970-01-01 02:00:00 +0000 UTC

Timers and Tickers are also controlled by this same mock clock. They will only execute when the clock is moved forward:

mock := clock.NewMock()
count := 0

// Kick off a timer to increment every 1 mock second.
go func() {
    ticker := mock.Ticker(1 * time.Second)
    for {
        <-ticker.C
        count++
    }
}()
runtime.Gosched()

// Move the clock forward 10 seconds.
mock.Add(10 * time.Second)

// This prints 10.
fmt.Println(count)

Documentation

Index

• type Clock
  • func New() Clock
• type Duration
• type Mock
  • func NewMock() *Mock
  • func (m *Mock) Add(d time.Duration)
  • func (m *Mock) After(d time.Duration) <-chan time.Time
  • func (m *Mock) AfterFunc(d time.Duration, f func()) *Timer
  • func (m *Mock) Now() time.Time
  • func (m *Mock) Set(t time.Time)
  • func (m *Mock) Since(t time.Time) time.Duration
  • func (m *Mock) Sleep(d time.Duration)
  • func (m *Mock) Tick(d time.Duration) <-chan time.Time
  • func (m *Mock) Ticker(d time.Duration) *Ticker
  • func (m *Mock) Timer(d time.Duration) *Timer
  • func (m *Mock) Until(t time.Time) time.Duration
  • func (m *Mock) WaitForAllTimers() time.Time
  • func (m *Mock) WithDeadline(parent context.Context, deadline time.Time) (context.Context, context.CancelFunc)
  • func (m *Mock) WithDeadlineCause(parent context.Context, deadline time.Time, cause error) (context.Context, context.CancelFunc)
  • func (m *Mock) WithTimeout(parent context.Context, timeout time.Duration) (context.Context, context.CancelFunc)
  • func (m *Mock) WithTimeoutCause(parent context.Context, timeout time.Duration, cause error) (context.Context, context.CancelFunc)
• type Ticker
  • func (t *Ticker) Reset(dur time.Duration)
  • func (t *Ticker) Stop()
• type Timer
  • func (t *Timer) Reset(d time.Duration) bool
  • func (t *Timer) Stop() bool

Examples

• Mock.After
• Mock.AfterFunc
• Mock.Sleep
• Mock.Ticker
• Mock.Timer

Types

type Clock

type Clock interface {
	After(d time.Duration) <-chan time.Time
	AfterFunc(d time.Duration, f func()) *Timer
	Now() time.Time
	Since(t time.Time) time.Duration
	Until(t time.Time) time.Duration
	Sleep(d time.Duration)
	Tick(d time.Duration) <-chan time.Time
	Ticker(d time.Duration) *Ticker
	Timer(d time.Duration) *Timer
	WithDeadline(parent context.Context, d time.Time) (context.Context, context.CancelFunc)
	WithDeadlineCause(parent context.Context, d time.Time, cause error) (context.Context, context.CancelFunc)
	WithTimeout(parent context.Context, timeout time.Duration) (context.Context, context.CancelFunc)
	WithTimeoutCause(parent context.Context, timeout time.Duration, cause error) (context.Context, context.CancelFunc)
}

Clock represents an interface to the functions in the standard library time package. Two implementations are available in the clock package. The first is a real-time clock which simply wraps the time package's functions. The second is a mock clock which will only change when programmatically adjusted.

func New

func New() Clock

New returns an instance of a real-time clock.

type Duration

type Duration = time.Duration

Re-export of time.Duration

type Mock

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

Mock represents a mock clock that only moves forward programmically. It can be preferable to a real-time clock when testing time-based functionality.

func NewMock

func NewMock() *Mock

NewMock returns an instance of a mock clock. The current time of the mock clock on initialization is the Unix epoch.

func (*Mock) Add

func (m *Mock) Add(d time.Duration)

Add moves the current time of the mock clock forward by the specified duration. This should only be called from a single goroutine at a time.

func (*Mock) After

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

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

Example

// Create a new mock clock.
clock := NewMock()
var count counter

ready := make(chan struct{})
// Create a channel to execute after 10 mock seconds.
go func() {
	ch := clock.After(10 * time.Second)
	close(ready)
	<-ch
	count.incr()
}()
<-ready

// Print the starting value.
fmt.Printf("%s: %d\n", clock.Now().UTC(), count.get())

// Move the clock forward 5 seconds and print the value again.
clock.Add(5 * time.Second)
fmt.Printf("%s: %d\n", clock.Now().UTC(), count.get())

// Move the clock forward 5 seconds to the tick time and check the value.
clock.Add(5 * time.Second)
fmt.Printf("%s: %d\n", clock.Now().UTC(), count.get())

Output:

1970-01-01 00:00:00 +0000 UTC: 0
1970-01-01 00:00:05 +0000 UTC: 0
1970-01-01 00:00:10 +0000 UTC: 1

func (*Mock) AfterFunc

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

AfterFunc waits for the duration to elapse and then executes a function in its own goroutine. A Timer is returned that can be stopped.

Example

// Create a new mock clock.
clock := NewMock()
var count counter
count.incr()

// Execute a function after 10 mock seconds.
clock.AfterFunc(10*time.Second, func() {
	count.incr()
})
gosched()

// Print the starting value.
fmt.Printf("%s: %d\n", clock.Now().UTC(), count.get())

// Move the clock forward 10 seconds and print the new value.
clock.Add(10 * time.Second)
fmt.Printf("%s: %d\n", clock.Now().UTC(), count.get())

Output:

1970-01-01 00:00:00 +0000 UTC: 1
1970-01-01 00:00:10 +0000 UTC: 2

func (*Mock) Now

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

Now returns the current wall time on the mock clock.

func (*Mock) Set

func (m *Mock) Set(t time.Time)

Set sets the current time of the mock clock to a specific one. This should only be called from a single goroutine at a time.

func (*Mock) Since

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

Since returns time since `t` using the mock clock's wall time.

func (*Mock) Sleep

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

Sleep pauses the goroutine for the given duration on the mock clock. The clock must be moved forward in a separate goroutine.

Example

// Create a new mock clock.
clock := NewMock()
var count counter

// Execute a function after 10 mock seconds.
go func() {
	clock.Sleep(10 * time.Second)
	count.incr()
}()
gosched()

// Print the starting value.
fmt.Printf("%s: %d\n", clock.Now().UTC(), count.get())

// Move the clock forward 10 seconds and print the new value.
clock.Add(10 * time.Second)
fmt.Printf("%s: %d\n", clock.Now().UTC(), count.get())

Output:

1970-01-01 00:00:00 +0000 UTC: 0
1970-01-01 00:00:10 +0000 UTC: 1

func (*Mock) Tick

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

Tick is a convenience function for Ticker(). It will return a ticker channel that cannot be stopped.

func (*Mock) Ticker

func (m *Mock) Ticker(d time.Duration) *Ticker

Ticker creates a new instance of Ticker.

Example

// Create a new mock clock.
clock := NewMock()
var count counter

ready := make(chan struct{})
// Increment count every mock second.
go func() {
	ticker := clock.Ticker(1 * time.Second)
	close(ready)
	for {
		<-ticker.C
		count.incr()
	}
}()
<-ready

// Move the clock forward 10 seconds and print the new value.
clock.Add(10 * time.Second)
fmt.Printf("Count is %d after 10 seconds\n", count.get())

// Move the clock forward 5 more seconds and print the new value.
clock.Add(5 * time.Second)
fmt.Printf("Count is %d after 15 seconds\n", count.get())

Output:

Count is 10 after 10 seconds
Count is 15 after 15 seconds

func (*Mock) Timer

func (m *Mock) Timer(d time.Duration) *Timer

Timer creates a new instance of Timer.

Example

// Create a new mock clock.
clock := NewMock()
var count counter

ready := make(chan struct{})
// Increment count after a mock second.
go func() {
	timer := clock.Timer(1 * time.Second)
	close(ready)
	<-timer.C
	count.incr()
}()
<-ready

// Move the clock forward 10 seconds and print the new value.
clock.Add(10 * time.Second)
fmt.Printf("Count is %d after 10 seconds\n", count.get())

Output:

Count is 1 after 10 seconds

func (*Mock) Until

func (m *Mock) Until(t time.Time) time.Duration

Until returns time until `t` using the mock clock's wall time.

func (*Mock) WaitForAllTimers

func (m *Mock) WaitForAllTimers() time.Time

WaitForAllTimers sets the clock until all timers are expired

func (*Mock) WithDeadline

func (m *Mock) WithDeadline(parent context.Context, deadline time.Time) (context.Context, context.CancelFunc)

WithDeadline returns a copy of the parent context with the deadline adjusted to be no later than d. If the parent's deadline is already earlier than d, WithDeadline(parent, d) is semantically equivalent to parent. The returned [Context.Done] channel is closed when the deadline expires, when the returned cancel function is called, or when the parent context's Done channel is closed, whichever happens first.

Canceling this context releases resources associated with it, so code should call cancel as soon as the operations running in this [Context] complete.

func (*Mock) WithDeadlineCause

func (m *Mock) WithDeadlineCause(parent context.Context, deadline time.Time, cause error) (context.Context, context.CancelFunc)

WithDeadlineCause behaves like [WithDeadline] but also sets the cause of the returned Context when the deadline is exceeded. The returned [CancelFunc] does not set the cause.

func (*Mock) WithTimeout

func (m *Mock) WithTimeout(parent context.Context, timeout time.Duration) (context.Context, context.CancelFunc)

WithTimeout returns WithDeadline(parent, time.Now().Add(timeout)).

Canceling this context releases resources associated with it, so code should call cancel as soon as the operations running in this [Context] complete:

func slowOperationWithTimeout(ctx context.Context) (Result, error) {
	ctx, cancel := context.WithTimeout(ctx, 100*time.Millisecond)
	defer cancel()  // releases resources if slowOperation completes before timeout elapses
	return slowOperation(ctx)
}

func (*Mock) WithTimeoutCause

func (m *Mock) WithTimeoutCause(parent context.Context, timeout time.Duration, cause error) (context.Context, context.CancelFunc)

WithTimeoutCause behaves like [WithTimeout] but also sets the cause of the returned Context when the timeout expires. The returned [CancelFunc] does not set the cause.

type Ticker

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

Ticker holds a channel that receives "ticks" at regular intervals.

func (*Ticker) Reset

func (t *Ticker) Reset(dur time.Duration)

Reset resets the ticker to a new duration.

func (*Ticker) Stop

func (t *Ticker) Stop()

Stop turns off the ticker.

type Timer

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

Timer represents a single event. The current time will be sent on C, unless the timer was created by AfterFunc.

func (*Timer) Reset

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

Reset changes the expiry time of the timer

func (*Timer) Stop

func (t *Timer) Stop() bool

Stop turns off the ticker.