Smarty
Testing in Go by example: Part 5An elegant and effective strategy for dealing with time in unit tests
Michael Whatcott
Michael Whatcott
 • 
September 15, 2015
Tags

For this installment of the Testing in Go series I'll share a really nifty way to deal with time in your unit tests. When the behavior you are testing depends on the current time it can be tricky to assert on the results because the current time is a moving target. So, usually we end up resorting to approximations in our assertions that, while functional, always bother me a bit. In some cases, depending directly on the system's current time prevents acceptable test coverage.

Consider this trivial example, which defines a calendar service with a method that identifies the current quarter of the current calendar year:

File: calendar.go (version 1)
package calendar

import "time"

type Calendar struct {
}

func NewCalendar() *Calendar {
	return &Calendar{}
}

func (this *Calendar) CurrentQuarter() int {
	month := time.Now().UTC().Month()
	if month < 4 {
		return 1
	} else if month < 7 {
		return 2
	} else if month < 10 {
		return 3
	} else {
		return 4
	}
}

Here's an obvious test we could write:

File: calendar_test.go (version 1)
package calendar

import (
	"testing"
	"time"
)

func TestCurrentQuarter(t *testing.T) {
	expected := time.Now().UTC().Month()
	actual := NewCalendar().CurrentQuarter()
	if expected != actual {
		t.Error("Expected:", expected, "Actual:", actual)
	}
}

(sigh) That test certainly leaves something to be desired as it only exercises one branch of the if statement. What would you do to ensure that the logic is correct in all cases? How can we exercise each branch of the if statement?

The answer is not to run the test once every three months for a few years to see if the right values always come out. Only slightly better would be to run the test several times, modifying the system clock in between test runs (cringe). Here's a possible solution that doesn't require fiddling with any system-level resources or waiting for months to get the results:

File: calendar.go (version 2)
package calendar

import "time"

/////////////////////////////////////////////

func now = func() time.Time {
	return time.Now()
}

/////////////////////////////////////////////

type Calendar struct {
}

func NewCalendar() *Calendar {
	return &Calendar{}
}

func (this *Calendar) CurrentQuarter() int {
	month := now().UTC().Month()
	if month < 4 {
		return 1
	} else if month < 7 {
		return 2
	} else if month < 10 {
		return 3
	} else {
		return 4
	}
}

There's not much different there. The code still appears to be calling time.Now() to get the current time. But we've introduced a layer of indirection which the test code can put to good use:

File: calendar_test.go (version 2)
package calendar

import (
	"testing"
)

func TestCurrentQuarter(t *testing.T) {
	cases := []struct{
		month   string
		quarter int
	}{
		{month: "01", quarter: 1},
		{month: "02", quarter: 1},
		{month: "03", quarter: 1},
		{month: "04", quarter: 2},
		{month: "05", quarter: 2},
		{month: "06", quarter: 2},
		{month: "07", quarter: 3},
		{month: "08", quarter: 3},
		{month: "09", quarter: 3},
		{month: "10", quarter: 4},
		{month: "11", quarter: 4},
		{month: "12", quarter: 4},
	}

	for _, test := range cases {
		parsed, _ := time.Parse("2006-01-02", fmt.Sprintf("2015-%s-15", test.month))
		// IMPORTANT: we are swapping out the `now` function with something we control!
		now = func() time.Time { return parsed }
		calendar := NewCalendar()
		actual := cal.CurrentQuarter()
		if actual != test.quarter {
			t.Error("Month:", test.month, 
				"Expected Quarter:", test.quarter, 
				"Actual Quarter:", actual)
		}
	}
}

I learned this approach a few years ago when, as a .Net developer, I was referred to a helpful post that used a simple static class with a static Func field which would forward to the .Net platform's DateTime.UTCNow capability. In the test code it is trivial to reassign that static Func field to whatever would facilitate testing the behavior that was dependent on the current time.

This approach is simple. This approach is great. It probably works for most of the code out there that depends on the system time. But it breaks down if you ever want to run multiple test functions that depend on now() in parallel. Lately, we've been writing a lot of parallel tests because they help us drive out bugs related to shared, package-level state.

When I initially set out to engineer a solution that would allow the unit test to run in parallel I came up with something like this:

File: calendar.go (version 3)
package calendar

import (
	"time"
)

/////////////////////////////////////////////

type Clock interface {
	Now() time.Time
}

type Calendar struct {
	clock Clock
}

/////////////////////////////////////////////

func NewCalendar(clock Clock) *Calendar {
	return &Calendar{clock: clock}
}

func (this *Calendar) CurrentQuarter() int {
	month := this.clock.Now().UTC().Month()
	if month < 4 {
		return 1
	} else if month < 7 {
		return 2
	} else if month < 10 {
		return 3
	} else {
		return 4
	}
}

So, this approach requires two different implementations of the Clock interface. One is for use in production--it simply returns the result of time.Now() every time. The other could be implemented in a *_test.go file in the calendar package and would return a specified time.Time. This implementation would be provided to the Calendar constructor in the test code. I'll leave figuring out the details of those implementations and the necessary changes to the test code (calendar_test.go version 3) as an exercise to the reader.

This solution is pretty good. Just pass in a Clock wherever time.Now() is needed. Because the Calendar no longer depends on package-level state the tests can run in parallel. But...now there's an annoying 'constructor' parameter that has to be passed in. And now we have two clock implementations hanging around. Okay, how about this slight improvement:

File: calendar.go (version 4)
package calendar

import (
	"time"
)

/////////////////////////////////////////////

type Clock interface {
	Now() time.Time
}

type Calendar struct {
	clock Clock
}

/////////////////////////////////////////////

func NewCalendar() *Calendar {
	return &Calendar{clock: NewProductionClock()}
}

func (this *Calendar) CurrentQuarter() int {
	month := this.clock.Now().UTC().Month()
	if month < 4 {
		return 1
	} else if month < 7 {
		return 2
	} else if month < 10 {
		return 3
	} else {
		return 4
	}
}

Instead of having to pass in a clock to the 'constructor' we simply use the in-production version of the clock by default. The test code (because it belongs in the same package) can reassign the Calendar.clock variable with a "testing" clock instance. This simplifies production wireup, which is nice.

But wait! We can do even better by taking advantage of Go's interesting function/method model:

File: calendar.go (version 5)
package calendar

import (
	"time"
)

/////////////////////////////////////////////

type Clock struct {
	instant time.Time
}

func (this *Clock) Now() time.Time {
	if this == nil {
		return time.Now()
	}
	return this.instant
}

/////////////////////////////////////////////

type Calendar struct {
	clock *Clock
}

func NewCalendar() *Calendar {
	return &Calendar{}
}

func (this *Calendar) CurrentQuarter() int {
	month := this.clock.Now().UTC().Month()
	if month < 4 {
		return 1
	} else if month < 7 {
		return 2
	} else if month < 10 {
		return 3
	} else {
		return 4
	}
}

Did you catch the very suble difference? We are no longer using an interface for the clock. Now there's only one implementation--the one you see. Did you also notice that we aren't initializing the *Clock field on the Calendar? That's because this isn't necessary anywhere in the production code. This is because of the nil check in the Now() method of the Clock.

In Go (unlike other languages like Python, Java, or C#) when you call a method on a pointer to a struct, the method is invoked and the nil pointer passed in as the receiver. From there, if any references to fields on the nil struct are accessed a "nil pointer dereference" panic ensues. So, we can take advantage of this to allow our production code to be very simple, not initializing the *Clock field anywhere to ensure that time.Now() is the result in production.

Now the test code (because it belongs to the same package) can initialize that field with an actual *Clock instance that provides a tailored time.Time. We've actually created an external package with all of this behavior: clock. Here's the complete example using our clock package:

File: calendar.go (version 6 - final)
package calendar

import (
	"time"

	"github.com/smartystreets/clock"
)

type Calendar struct {
	clock *clock.Clock
}

func NewCalendar() *Calendar {
	// Notice: no constructor parameters and no initilization of the *Clock!
	return &Calendar{}
}

func (this *Calendar) CurrentQuarter() int {
	month := this.clock.UTCNow().Month()
	if month < 4 {
		return 1
	} else if month < 7 {
		return 2
	} else if month < 10 {
		return 3
	} else {
		return 4
	}
}
File: calendar_test.go
package calendar

import (
	"testing"
	"time"

	"github.com/smartystreets/clock"
)

func TestCurrentQuarter(t *testing.T) {
	cases := []struct{
		month   string
		quarter int
	}{
		{month: "01", quarter: 1},
		{month: "02", quarter: 1},
		{month: "03", quarter: 1},
		{month: "04", quarter: 2},
		{month: "05", quarter: 2},
		{month: "06", quarter: 2},
		{month: "07", quarter: 3},
		{month: "08", quarter: 3},
		{month: "09", quarter: 3},
		{month: "10", quarter: 4},
		{month: "11", quarter: 4},
		{month: "12", quarter: 4},
	}

	for _, test := range cases {
		parsed, _ := time.Parse("2006-01-02", fmt.Sprintf("2015-%s-15", test.month))
		cal := NewCalendar()
		cal.clock = clock.Freeze(parsed)
		actual := cal.CurrentQuarter()
		if actual != test.quarter {
			t.Error("Month:", test.month, "Expected Quarter:", test.quarter, "Actual Quarter:", actual)
		}
	}
}

The approach we've taken with the clock package can be utilized with any package-level resource that you want be able to replace at the struct-level. Examples:

  • time.Sleep (included with the clock package; see clock.StayAwake())
  • log.Println (see our logging package for a similar implementation)
  • os.Getenv(...)
  • flag.String
  • rand.Reader

Can you think of any other applications for this approach?

Happy testing!

Subscribe to our blog!
Learn more about RSS feeds here.
rss feed iconSubscribe Now
Read our recent posts
World Juggling Day: Tips from Smarty’s jester
Arrow Icon
It’s that time of year when we toss aside our fears and woes and throw our hands up in celebration; World Juggling Day is here. Whether you toss hacky sacs, bowling pins, flaming torches, or your cookies, juggling has been a long-standing form of fun, fitness, and flair. Let’s talk about this quirky holiday. History of jugglingThe history of juggling is rich and dates back almost&nbsp;4,000 years. In ancient Egyptian times, tombs shared depictions of juggling. Greeks and Romans also tossed their hats into the juggling arena, yet juggling began to be scorned and overlooked by many in the Middle Ages due to claims that jugglers dealt with immorality and witchcraft.
Wizardry - How Smarty makes professional improvement magical, and you can, too
Arrow Icon
Alright, gather 'round, fellow wizards and witches! It's time to unveil the secrets to mastering the mystical art of professional development at Smarty. Yes, “wizardry” typically refers to wearing cloaks, wielding wands, riding broomsticks, and mixing potions. At Smarty, we think of “wizardry” as being the best at doing what we do. We’re going above and beyond to not only become experts in our field but also stay that way through shifts in technology and culture. However, being the best shouldn’t be an afterthought; at Smarty, it’s not.
Authentic culture: Exploring the depths with Smarty
Arrow Icon
Navigating the depths of corporate cultureIn today's business world, many companies create a surface-level culture within their company structures but stop there, never seeming to invest fully in deepening a healthy culture. Surface-level culture can be visually appealing and immediately gratifying. Imagine, for example, a delicious cake. It’s beautifully decorated but tastes off or is missing an ingredient that spoils the final product. An intentional and deep culture is hard work. It takes time, action, correction, and honest feedback from everyone in the company.