README

clockwork

Mentioned in Awesome Go

GitHub Workflow Status Go Report Card Go Version go.dev reference

A simple fake clock for Go.

Usage

Replace uses of the time package with the clockwork.Clock interface instead.

For example, instead of using time.Sleep directly:

func myFunc() {
	time.Sleep(3 * time.Second)
	doSomething()
}

Inject a clock and use its Sleep method instead:

func myFunc(clock clockwork.Clock) {
	clock.Sleep(3 * time.Second)
	doSomething()
}

Now you can easily test myFunc with a FakeClock:

func TestMyFunc(t *testing.T) {
	c := clockwork.NewFakeClock()

	// Start our sleepy function
	var wg sync.WaitGroup
	wg.Add(1)
	go func() {
		myFunc(c)
		wg.Done()
	}()

	// Ensure we wait until myFunc is sleeping
	c.BlockUntil(1)

	assertState()

	// Advance the FakeClock forward in time
	c.Advance(3 * time.Second)

	// Wait until the function completes
	wg.Wait()

	assertState()
}

and in production builds, simply inject the real clock instead:

myFunc(clockwork.NewRealClock())

See example_test.go for a full example.

Credits

clockwork is inspired by @wickman's threaded fake clock, and the Golang playground

License

Apache License, Version 2.0. Please see License File for more information.

Expand ▾ Collapse ▴

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Clock

type Clock interface {
	After(d time.Duration) <-chan time.Time
	Sleep(d time.Duration)
	Now() time.Time
	Since(t time.Time) time.Duration
	NewTicker(d time.Duration) Ticker
}

    Clock provides an interface that packages can use instead of directly using the time module, so that chronology-related behavior can be tested

    func NewRealClock

    func NewRealClock() Clock

      NewRealClock returns a Clock which simply delegates calls to the actual time package; it should be used by packages in production.

      type FakeClock

      type FakeClock interface {
      	Clock
      	// Advance advances the FakeClock to a new point in time, ensuring any existing
      	// sleepers are notified appropriately before returning
      	Advance(d time.Duration)
      	// BlockUntil will block until the FakeClock has the given number of
      	// sleepers (callers of Sleep or After)
      	BlockUntil(n int)
      }

        FakeClock provides an interface for a clock which can be manually advanced through time

        func NewFakeClock

        func NewFakeClock() FakeClock

          NewFakeClock returns a FakeClock implementation which can be manually advanced through time for testing. The initial time of the FakeClock will be an arbitrary non-zero time.

          func NewFakeClockAt

          func NewFakeClockAt(t time.Time) FakeClock

            NewFakeClockAt returns a FakeClock initialised at the given time.Time.

            type Ticker

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

              Ticker provides an interface which can be used instead of directly using the ticker within the time module. The real-time ticker t provides ticks through t.C which becomes now t.Chan() to make this channel requirement definable in this interface.