README
¶
Clock
A drop in (almost) replacement for the system time package. It provides a way
to make scheduled calls, timers and tickers deterministic in tests. By default
it forwards all calls to the system time package. In test, however, it is
possible to enable the frozen clock mode, and advance time manually to make
scheduled even trigger at certain moments.
Usage
package foo
import (
"time"
"github.com/mailgun/holster/clock"
. "gopkg.in/check.v1"
)
type FooSuite struct{}
var _ = Suite(&FooSuite{})
func (s *FooSuite) SetUpTest(c *C) {
// Freeze switches the clock package to the frozen clock mode. You need to
// advance time manually from now on. Note that all scheduled events, timers
// and ticker created before this call keep operating in real time.
//
// The initial time is set to 0 here, but you can set any datetime.
clock.Freeze(time.Time(0))
}
func (s *FooSuite) TearDownTest(c *C) {
// Reverts the effect of Freeze in test setup.
clock.Unfreeze()
}
func (s *FooSuite) TestSleep(c *C) {
var fired bool
clock.AfterFunc(100*time.Millisecond, func() {
fired = true
})
clock.Advance(93*time.Millisecond)
// Advance will make all fire all events, timers, tickers that are
// scheduled for the passed period of time. Note that scheduled functions
// are called from within Advanced unlike system time package that calls
// them in their own goroutine.
c.Assert(clock.Advance(6*time.Millisecond), Equals, 97*time.Millisecond)
c.Assert(fired, Equals, false)
c.Assert(clock.Advance(1*time.Millisecond), Equals, 100*time.Millisecond)
c.Assert(fired, Equals, true)
}
Documentation
¶
Overview ¶
Package clock provides the same functions as the system package time. In production it forwards all calls to the system time package, but in tests the time can be frozen by calling Freeze function and from that point it has to be advanced manually with Advance function making all scheduled calls deterministic.
The functions provided by the package have the same parameters and return values as their system counterparts with a few exceptions. Where either *time.Timer or *time.Ticker is returned by a system function, the clock package counterpart returns clock.Timer or clock.Ticker interface respectively. The interfaces provide API as respective structs except C is not a channel, but a function that returns <-chan time.Time.
Index ¶
- Constants
- Variables
- func Advance(d time.Duration) time.Duration
- func After(d time.Duration) <-chan time.Time
- func Now() time.Time
- func Sleep(d time.Duration)
- func Tick(d time.Duration) <-chan time.Time
- func Unfreeze()
- func Wait4Scheduled(count int, timeout time.Duration) bool
- type Clock
- type Duration
- type DurationJSON
- type Location
- type Month
- type ParseError
- type Ticker
- type Time
- type Timer
- type Unfreezer
- type Weekday
Constants ¶
const ( Nanosecond = time.Nanosecond Microsecond = time.Microsecond Millisecond = time.Millisecond Second = time.Second Minute = time.Minute Hour = time.Hour Sunday = time.Sunday Monday = time.Monday Tuesday = time.Tuesday Wednesday = time.Wednesday Thursday = time.Thursday Friday = time.Friday Saturday = time.Saturday January = time.January February = time.February March = time.March April = time.April May = time.May June = time.June July = time.July August = time.August September = time.September October = time.October November = time.November December = time.December ANSIC = time.ANSIC UnixDate = time.UnixDate RubyDate = time.RubyDate RFC822 = time.RFC822 RFC822Z = time.RFC822Z RFC850 = time.RFC850 RFC1123 = time.RFC1123 RFC1123Z = time.RFC1123Z RFC3339 = time.RFC3339 RFC3339Nano = time.RFC3339Nano Kitchen = time.Kitchen Stamp = time.Stamp StampMilli = time.StampMilli StampMicro = time.StampMicro StampNano = time.StampNano )
Variables ¶
var ( UTC = time.UTC Local = time.Local )
Functions ¶
func Advance ¶
Makes the deterministic time move forward by the specified duration, firing timers along the way in the natural order. It returns how much time has passed since it was frozen. So you can assert on the return value in tests to make it explicit where you stand on the deterministic time scale.
Types ¶
type Clock ¶
type Clock interface {
Now() time.Time
Sleep(d time.Duration)
After(d time.Duration) <-chan time.Time
NewTimer(d time.Duration) Timer
AfterFunc(d time.Duration, f func()) Timer
NewTicker(d time.Duration) Ticker
Tick(d time.Duration) <-chan time.Time
Wait4Scheduled(n int, timeout time.Duration) bool
}
Clock is an interface that mimics the one of the SDK time package.
type Duration ¶
func ParseDuration ¶
type DurationJSON ¶
type DurationJSON struct {
Duration Duration
}
func NewDurationJSON ¶
func NewDurationJSON(v interface{}) (DurationJSON, error)
func NewDurationJSONOrPanic ¶
func NewDurationJSONOrPanic(v interface{}) DurationJSON
func (DurationJSON) MarshalJSON ¶
func (d DurationJSON) MarshalJSON() ([]byte, error)
func (DurationJSON) String ¶
func (d DurationJSON) String() string
func (*DurationJSON) UnmarshalJSON ¶
func (d *DurationJSON) UnmarshalJSON(b []byte) error
type Location ¶
func LoadLocation ¶
type ParseError ¶
type ParseError = time.ParseError
type Timer ¶
Timer see time.Timer.
func NewStoppedTimer ¶
func NewStoppedTimer() Timer
NewStoppedTimer returns a stopped timer. Call Reset to get it ticking.
type Unfreezer ¶
type Unfreezer struct{}
Source Files