clockwork

package module
Version: v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Apr 21, 2022 License: Apache-2.0 Imports: 4 Imported by: 1,242

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.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddToContext added in v0.2.3

func AddToContext(ctx context.Context, clock Clock) context.Context

AddToContext creates a derived context that references the specified clock.

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
	NewTimer(d time.Duration) Timer
}

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

func FromContext added in v0.2.3

func FromContext(ctx context.Context) Clock

FromContext extracts a clock from the context. If not present, a real clock is returned.

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 added in v0.2.0

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.

type Timer added in v0.3.0

type Timer interface {
	Chan() <-chan time.Time
	Reset(d time.Duration) bool
	Stop() bool
}

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

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL