Deterministic Go Tests: How to Forbid `time.Now()`

type Session struct {
    UserID    string
    ExpiresAt time.Time
}

// IsActive checks if the session is still valid.
func (s *Session) IsActive() bool {
    // This is the source of our problems!
    return time.Now().Before(s.ExpiresAt)
}

The Hero's Approach: Injecting Time

The solution isn't to stop dealing with time; it's to treat time as a dependency, just like you would a database connection or a logger. This is a classic application of Dependency Injection (DI).

Instead of your functions reaching out to the time package to get the current time, you provide the time to them. The most idiomatic way to do this in Go is with an interface.

Defining a Clock Interface

Let's start by defining a simple interface for a clock:

// clock.go
package myapp

import "time"

// Clock is an interface that abstracts the `time` package.
// This allows for deterministic testing.
type Clock interface {
    Now() time.Time
}

Next, we create a real implementation that we'll use in our production code. This struct will call the real time.Now().

// clock.go (continued)

// RealClock is the production implementation of the Clock interface.
type RealClock struct{}

// Now returns the current time.
func (c RealClock) Now() time.Time {
    return time.Now()
}

Refactoring Our Code

Now, we refactor our IsActive method to accept a Clock.

// session.go

// IsActive now accepts a Clock to make it testable.
func (s *Session) IsActive(clock Clock) bool {
    return clock.Now().Before(s.ExpiresAt)
}

This is a small change, but its impact is massive. Our function is no longer at the mercy of the system clock. It's now pure and deterministic: its output depends only on the session and the clock you give it.

Testing with a Mock Clock

In our tests, we can now create a mock clock that returns any time we want.

// session_test.go
package myapp_test

// MockClock is a test implementation of the Clock interface.
// It allows us to control time in our tests.
type MockClock struct {
    CurrentTime time.Time
}

// Now returns the fixed time set in CurrentTime.
func (c *MockClock) Now() time.Time {
    return c.CurrentTime
}

func TestSessionIsActive(t *testing.T) {
    // Arrange: Set a fixed point in time.
    fixedTime := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
    mockClock := &MockClock{CurrentTime: fixedTime}

    // Arrange: Create a session that expires in 10 minutes.
    session := &myapp.Session{
        UserID:    "user-123",
        ExpiresAt: fixedTime.Add(10 * time.Minute),
    }

    // Act
    isActive := session.IsActive(mockClock)

    // Assert
    if !isActive {
        t.Errorf("Expected session to be active, but it wasn't")
    }
}

func TestSessionIsExpired(t *testing.T) {
    // Arrange: Set a fixed point in time.
    fixedTime := time.Date(2025, 1, 15, 12, 0, 0, 0, time.UTC)
    mockClock := &MockClock{CurrentTime: fixedTime}

    // Arrange: Create a session that expired 1 second ago.
    session := &myapp.Session{
        UserID:    "user-123",
        ExpiresAt: fixedTime.Add(-1 * time.Second),
    }

    // Act
    isActive := session.IsActive(mockClock)

    // Assert
    if isActive {
        t.Errorf("Expected session to be expired, but it was active")
    }
}

Look at that! Our tests are now rock-solid. They will produce the exact same result every single time, on any machine, forever. We have achieved determinism.

Building the Guardrails: Static Analysis to the Rescue

Adopting this pattern is great, but how do you enforce it across a team? It's easy for a developer under pressure to forget the rule and slip a quick time.Now() into a test file. This is where static analysis comes in.

We can write a custom linter using Go's powerful go/analysis package that automatically scans our test files and flags any forbidden calls to time.Now().

Here’s what a simple analyzer looks like. Create a new directory (e.g., tools/notimenow) and place this code inside a main.go file.

// tools/notimenow/main.go
package main

import (
    "go/ast"
    "go/types"
    "strings"

    "golang.org/x/tools/go/analysis"
    "golang.org/x/tools/go/analysis/singlechecker"
)

// Analyzer is the static analysis tool that forbids `time.Now()` in test files.
var Analyzer = &analysis.Analyzer{
    Name: "notimenow",
    Doc:  "forbids the use of time.Now() in test files",
    Run:  run,
}

func main() {
    // singlechecker.Main is a helper to run the analyzer.
    singlechecker.Main(Analyzer)
}

func run(pass *analysis.Pass) (interface{}, error) {
    for _, file := range pass.Files {
        // We only care about test files.
        filename := pass.Fset.File(file.Pos()).Name()
        if !strings.HasSuffix(filename, "_test.go") {
            continue
        }

        // ast.Inspect traverses the Abstract Syntax Tree of the file.
        ast.Inspect(file, func(n ast.Node) bool {
            // We are looking for a function call, like `myFunc()`.
            call, ok := n.(*ast.CallExpr)
            if !ok {
                return true // Not a call expression, continue walking the tree.
            }

            // The function being called must be a selector, like `pkg.Func`.
            selector, ok := call.Fun.(*ast.SelectorExpr)
            if !ok {
                return true // Not a selector, continue.
            }

            // The function's name must be `Now`.
            if selector.Sel.Name != "Now" {
                return true
            }

            // Now we check if the selector's package is `time`.
            // We use the type information to be 100% sure.
            if ident, ok := selector.X.(*ast.Ident); ok {
                if obj := pass.TypesInfo.ObjectOf(ident); obj != nil {
                    if pkg, ok := obj.(*types.PkgName); ok && pkg.Imported().Path() == "time" {
                        // We found it! Report an error.
                        pass.Reportf(n.Pos(), "direct call to time.Now() is forbidden in tests; use a Clock interface")
                    }
                }
            }
            return true
        })
    }
    return nil, nil
}

Integrating Your New Superpower

With our analyzer written, we can now use it to guard our codebase.

First, build the analyzer executable:

# From your project's root directory
go build -o bin/notimenow ./tools/notimenow

Now, you can run it with go vet, which has a -vettool flag to specify a custom analysis tool.

# Run the analyzer across all packages in your project
go vet -vettool=$(pwd)/bin/notimenow ./...

If any _test.go file contains a time.Now() call, the command will fail and print the error message we defined, pointing directly to the offending line. The magic happens when you add this command to your CI/CD pipeline. It becomes an automated gatekeeper, ensuring that non-deterministic tests never get merged into your main branch.

For more advanced setups, you can integrate this custom linter into golangci-lint, which provides a unified and highly configurable way to run many linters at once. This approach turns a simple convention into an unbreakable rule.

Embracing Determinism

Banning time.Now() from tests might seem strict, but it’s a powerful step toward a more professional and robust engineering culture. It forces us to write code that is decoupled, explicit, and, most importantly, testable in a way that is repeatable and reliable.

By treating time as a dependency and enforcing this rule with static analysis, you eliminate an entire class of flaky tests, save countless hours of debugging, and build a test suite that your team can truly trust. It's a small investment in discipline that pays massive dividends in code quality and developer sanity.