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 interchangable. For example, if you had an Application type:
import "github.com/benbjohnson/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/benbjohnson/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, Jan 1, 1970 UTC).
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 := clock.Ticker(1 * time.Second)
for {
<-ticker.C
count++
}
}()
runtime.Gosched()
// Move the clock forward 10 second.
mock.Add(10 * time.Second)
// This prints 10.
fmt.Println(count)
Documentation
¶
Index ¶
- type Calls
- type Clock
- type 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) 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) Wait(s Calls)
- type Ticker
- type Timer
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Calls ¶
type Calls struct {
After uint32
AfterFunc uint32
Now uint32
Sleep uint32
Tick uint32
Ticker uint32
Timer uint32
}
Calls keeps track of the count of calls for each of the methods on the Clock interface.
type Clock ¶
type Clock interface {
After(d time.Duration) <-chan time.Time
AfterFunc(d time.Duration, f func()) *Timer
Now() time.Time
Sleep(d time.Duration)
Tick(d time.Duration) <-chan time.Time
Ticker(d time.Duration) *Ticker
Timer(d time.Duration) *Timer
}
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 make forward progress when programmatically adjusted.
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 ¶
Add moves the current time of the mock clock forward by the duration. This should only be called from a single goroutine at a time.
func (*Mock) After ¶
After waits for the duration to elapse and then sends the current time on the returned channel.
Example ¶
package main
import (
"fmt"
"runtime"
"time"
"github.com/facebookgo/clock"
)
func main() {
// Create a new mock clock.
clock := clock.NewMock()
count := 0
// Create a channel to execute after 10 mock seconds.
go func() {
<-clock.After(10 * time.Second)
count = 100
}()
runtime.Gosched()
// Print the starting value.
fmt.Printf("%s: %d\n", clock.Now().UTC(), count)
// 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)
// 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)
}
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: 100
func (*Mock) AfterFunc ¶
AfterFunc waits for the duration to elapse and then executes a function. A Timer is returned that can be stopped.
Example ¶
package main
import (
"fmt"
"runtime"
"time"
"github.com/facebookgo/clock"
)
func main() {
// Create a new mock clock.
clock := clock.NewMock()
count := 0
// Execute a function after 10 mock seconds.
clock.AfterFunc(10*time.Second, func() {
count = 100
})
runtime.Gosched()
// Print the starting value.
fmt.Printf("%s: %d\n", clock.Now().UTC(), count)
// 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)
}
Output: 1970-01-01 00:00:00 +0000 UTC: 0 1970-01-01 00:00:10 +0000 UTC: 100
func (*Mock) Sleep ¶
Sleep pauses the goroutine for the given duration on the mock clock. The clock must be moved forward in a separate goroutine.
Example ¶
package main
import (
"fmt"
"runtime"
"time"
"github.com/facebookgo/clock"
)
func main() {
// Create a new mock clock.
clock := clock.NewMock()
count := 0
// Execute a function after 10 mock seconds.
go func() {
clock.Sleep(10 * time.Second)
count = 100
}()
runtime.Gosched()
// Print the starting value.
fmt.Printf("%s: %d\n", clock.Now().UTC(), count)
// 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)
}
Output: 1970-01-01 00:00:00 +0000 UTC: 0 1970-01-01 00:00:10 +0000 UTC: 100
func (*Mock) Tick ¶
Tick is a convenience function for Ticker(). It will return a ticker channel that cannot be stopped.
func (*Mock) Ticker ¶
Ticker creates a new instance of Ticker.
Example ¶
package main
import (
"fmt"
"runtime"
"time"
"github.com/facebookgo/clock"
)
func main() {
// Create a new mock clock.
clock := clock.NewMock()
count := 0
// Increment count every mock second.
go func() {
ticker := clock.Ticker(1 * time.Second)
for {
<-ticker.C
count++
}
}()
runtime.Gosched()
// 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)
// 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)
}
Output: Count is 10 after 10 seconds Count is 15 after 15 seconds
func (*Mock) Timer ¶
Timer creates a new instance of Timer.
Example ¶
package main
import (
"fmt"
"runtime"
"time"
"github.com/facebookgo/clock"
)
func main() {
// Create a new mock clock.
clock := clock.NewMock()
count := 0
// Increment count after a mock second.
go func() {
timer := clock.Timer(1 * time.Second)
<-timer.C
count++
}()
runtime.Gosched()
// 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)
}
Output: Count is 1 after 10 seconds
Source Files