Testing in Go by example: Part 5

 • 
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.
Subscribe Now
Get our latest eBook!
Evaluating a geocoding tool?
Get the buyer's guide
smarty logo
Download now
Read our recent posts
Rising Parcel Shipping Costs in 2022: How to Cut Your Shipping Expenses
Arrow Icon
Parcel shipping costs have been rising since 2020. We’ve all seen inflation on the consumer end, whether we’re checking out online or paying at the gas pump. And skyrocketing freight rates have made headlines. Today, we’re going to focus on the impact of the increasing cost of shipping on your business and what you can do about it. But don’t lose hope—while we’re going to explore climbing shipment costs in this article, we’ll also chat about what your business can do to make shipping more efficient.
How to Clean Address Data For the Holiday Rush
Arrow Icon
It’s November, and online shopping is ramping up to its climactic end-of-year blitz. www. blackfriday. com estimates that between Thanksgiving and Black Friday of this year, consumers will spend approximately $13 billion 1. That’s great news for your business. But if you don’t have the right tools in place to help you meet that demand, you might be left wishing you had better prepare. Staffing may be one issue for many businesses. According to the US Chamber of Commerce, the wholesale and retail trade industry has experienced the second-highest quit rate of all industries since November 20202.
Helpful Hints to Authenticating Your APIs
Arrow Icon
We brought out the big guns in the way of our Development Team Lead, Kent Gividen, in a webinar all about authenticating your APIs. He went over some of his most useful tips and tricks that he uses to ensure APIs are authenticated. Was it helpful? You betcha. You wanna get the sparknotes? Read on. Common and Not-So-Common APIs to Know About Kent began by outlining the APIs that he has run into the most in his years as a developer. Some of them he dug into a little deeper than others, but these are all useful to be aware of.

The leader in location data intelligence

Ready to get started?