New 42-day free trial
Smarty

Testing in Go by example: Part 5

Michael Whatcott
Michael Whatcott
 | 
September 15, 2015
Tags
Smarty header pin graphic

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 icon
Subscribe Now
Read our recent posts
Improving user/customer experience in every industry with clean address data
Arrow Icon
You finally track down an essential addition to your collector’s set of [insert item of your choice], and you're hyped to buy it until the chaos begins. The cart is hidden in a fly-out on the side, cluttered with blocky, overwhelming text. You spend way too long just trying to find the "Proceed to Checkout" button. 👎 That’s bad UI (user interface): messy, confusing design that makes navigation a chore. You make it to the checkout and start entering your info, but the site keeps rejecting your address.
Dashboard essentials for Smarty users
Arrow Icon
The Smarty dashboard is your central hub for managing address verification, geocoding, and property data services. Whether you're just starting or looking to optimize your current setup, understanding the dashboard's full capabilities can significantly streamline your address data operations. We recently held a webinar in which we reviewed all of the Smarty dashboard's items and features. Missed it? That's OK; we've got all the information right here. You can expect to read about:Accessing your dashboardSetting up your account for successUnderstanding your active subscriptionsManaging API keys effectivelyStreamlining billing and financial managementStaying informed with smart notificationsTeam management and access controlsWeb toolsMaking the most of free trialsKey takeawaysLet’s get going!Accessing your dashboardGetting to your dashboard is straightforward.
Take charge of your API usage with Smarty’s key management features
Arrow Icon
Ever wondered, “Where did all my lookups go?!” Without proper API management, you may burn through your lookups quicker, experience runaway code, and encounter unexpected usage. That’s why Smarty created usage by key (included in all annual plans) and limit by key (included in some plans; you can add them by contacting sales) for its APIs. Why key management mattersCommon API usage challenges (problems to solve):Unexpected spikes in lookupsDifficulty tracking specific key usageWhich keys are calling which Smarty licenseNeed for better control over API consumptionDifficulty allocating Smarty lookups across an organizationWith Smarty's key management features, you gain more control by having better visibility of your usage, eliminating the element of surprise (you know, the bad kind, like when you’re suddenly out of lookups).

Ready to get started?