mocktime

README

mocktime

This package provides an easy way to mock specific functions in the time package:

import "github.com/nitroshare/mocktime"

// Same as time.Now()
mocktime.Now()

// Mock Now() and After()
mocktime.Mock()
defer mocktime.Unmock()

// All calls to Now() will return the same time...
mocktime.Now()

// ...until the time is advanced
mocktime.Advance(5 * time.Second)

// ...or explicitly set
mocktime.Set(time.Date(2025, time.May, 1, 0, 0, 0, 0, time.UTC))

// Calls to After() will block until the time is advanced (in another
// goroutine, for example)
<-mocktime.After(5 * time.Second)

// A drop-in replacement for time.Timer is provided:
t := mocktime.NewTimer(10 * time.Second)
<-t.C
t.Stop()

// ...as well as time.Ticker:
t := mocktime.NewTicker(1 * time.Second)
<-t.C
t.Reset(2 * time.Second)
t.Stop()

Advanced Usage

A special utility function is provided that blocks until the next call to After():

chanDone := make(chan any)

go func() {

    // Normally, this will block until Set() or Advance() is called
    <-mocktime.After(5 * time.Second)

    close(chanDone)
}()

// Advance the time to the expiry of the After() call above; we don't need to
// worry if the goroutine has reached the After() call or not when this
// function is called as it will block until After() is called
mocktime.AdvanceToAfter()

// This read is guaranteed to succeed because the read on After() in the
// goroutine is unblocked
<-chanDone

Documentation

Index

• Variables
• func Advance(d time.Duration)
• func AdvanceToAfter()
• func Mock()
• func MockAfter(d time.Duration) <-chan time.Time
• func MockNow() time.Time
• func Set(t time.Time)
• func Unmock()
• type Ticker
  • func NewTicker(d time.Duration) *Ticker
  • func (t *Ticker) Reset(d time.Duration)
  • func (t *Ticker) Stop()
• type Timer
  • func NewTimer(d time.Duration) *Timer
  • func (t *Timer) Stop() bool

Variables

var (
	// Now normally points to time.Now but can also be pointed to with
	// MockNow.
	Now func() time.Time

	// After normally points to time.After but can also be pointed to with
	// MockAfter.
	After func(d time.Duration) <-chan time.Time
)

Functions

func Advance

func Advance(d time.Duration)

Advance advances the mocked time by the specified duration.

func AdvanceToAfter

func AdvanceToAfter()

AdvanceToAfter is a synchronization function that will advance to the time of the next After() call, waiting for a call to After() if necessary. Note that this will also include timers.

func Mock

func Mock()

Mock replaces the time functions in this package with their mocked equivalents. Note that this is intended to be called at the beginning of a test and used with an associated defer Unmock() call. It is not safe for Mock or Unmock to be called from other goroutines, although the other mocked functions and types may be used anywhere while mocking is active.

func MockAfter

func MockAfter(d time.Duration) <-chan time.Time

MockAfter returns a channel that will send when the specified duration elapses via calls to Set or Advance.

func MockNow

func MockNow() time.Time

MockNow returns the current mocked time. Although this can be set by reassigning Now, this is typically handled automatically by Mock.

func Set

func Set(t time.Time)

Set explicitly sets the mocked time.

func Unmock

func Unmock()

Unmock replaces the mocked time functions with their original equivalents.

Types

type Ticker

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

Ticker provides a drop-in replacement for time.Ticker.

func NewTicker

func NewTicker(d time.Duration) *Ticker

NewTicker creates a new Ticker that will send on the channel C every time the specified duration elapses.

func (*Ticker) Reset

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

Reset stops the ticker and restarts it with the specified duration.

func (*Ticker) Stop

func (t *Ticker) Stop()

Stop ends the ticker.

type Timer

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

Timer provides a drop-in replacement for time.Timer.

func NewTimer

func NewTimer(d time.Duration) *Timer

NewTimer creates a new Timer that will send on the channel C when the specified duration expires.

func (*Timer) Stop

func (t *Timer) Stop() bool

Stop ends the timer.