Test Data Builders in Go That Keep Your Tests Short

A struct with eight fields makes a test either long or vague. Written out in full, every test repeats the same seven values to vary the eighth, and a reader has to compare them line by line to find the difference. Written with a shared fixture, the test hides what it depends on. The test data builder pattern fixes both: a function that returns a valid object, and small methods that change one thing at a time.

This article builds a User builder on Go 1.25.6 and shows how it reads in a table test. It also covers the lighter options, since Go gives you more than one way to do this.

The object

package main

import "time"

type Address struct{ Street, City, Country string }

type User struct {
	ID       int
	Name     string
	Email    string
	Admin    bool
	Joined   time.Time
	Address  Address
	Verified bool
}

// Validate has several rules, so tests need many different users.
func (u User) Validate() []string {
	var errs []string
	if u.Name == "" {
		errs = append(errs, "name required")
	}
	if u.Email == "" {
		errs = append(errs, "email required")
	}
	if u.Admin && !u.Verified {
		errs = append(errs, "admin must be verified")
	}
	if u.Address.Country == "" {
		errs = append(errs, "country required")
	}
	return errs
}

func main() {}

User.Validate has four rules: a name, an email and a country are required, and an administrator must be verified. A thorough test needs a user that satisfies every rule, and then a user that breaks each rule in turn. The base user is where the repetition lives.

The builder

package main

import (
	"slices"
	"testing"
	"time"
)

// UserBuilder starts from a valid user; each method changes one thing.
type UserBuilder struct{ u User }

func aUser() UserBuilder {
	return UserBuilder{User{
		ID: 1, Name: "Ada", Email: "[email protected]", Verified: true,
		Joined:  time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC),
		Address: Address{"1 Main St", "Lisbon", "PT"},
	}}
}

func (b UserBuilder) Named(n string) UserBuilder     { b.u.Name = n; return b }
func (b UserBuilder) WithoutEmail() UserBuilder      { b.u.Email = ""; return b }
func (b UserBuilder) Admin() UserBuilder             { b.u.Admin = true; return b }
func (b UserBuilder) Unverified() UserBuilder        { b.u.Verified = false; return b }
func (b UserBuilder) InCountry(c string) UserBuilder { b.u.Address.Country = c; return b }
func (b UserBuilder) Build() User                    { return b.u }

func TestValidate(t *testing.T) {
	cases := []struct {
		name string
		user User
		want []string
	}{
		{"valid", aUser().Build(), nil},
		{"no name", aUser().Named("").Build(), []string{"name required"}},
		{"no email", aUser().WithoutEmail().Build(), []string{"email required"}},
		{"unverified admin", aUser().Admin().Unverified().Build(), []string{"admin must be verified"}},
		{"no country", aUser().InCountry("").Build(), []string{"country required"}},
		{"two problems", aUser().Named("").WithoutEmail().Build(), []string{"name required", "email required"}},
	}
	for _, c := range cases {
		t.Run(c.name, func(t *testing.T) {
			got := c.user.Validate()
			t.Logf("%v", got)
			if !slices.Equal(got, c.want) {
				t.Fatalf("got %v want %v", got, c.want)
			}
		})
	}
}

go test -count=1 -v . 2>&1 | grep -vE "^(=== RUN|=== PAUSE|=== CONT|PASS|ok)" | sed -E "s/ \([0-9.]+s\)//; s#^ +[a-z_]+\.go:[0-9]+: #    #"

    []
    [name required]
    [email required]
    [admin must be verified]
    [country required]
    [name required email required]
--- PASS: TestValidate
    --- PASS: TestValidate/valid
    --- PASS: TestValidate/no_name
    --- PASS: TestValidate/no_email
    --- PASS: TestValidate/unverified_admin
    --- PASS: TestValidate/no_country
    --- PASS: TestValidate/two_problems

aUser() returns a UserBuilder holding a valid user: every required field set, verified, with an address. Each method changes one thing and returns the builder: Named, WithoutEmail, Admin, Unverified, InCountry. Build() hands back the User.

The table reads like a specification. aUser().Named("").Build() is "a user with no name", and nothing else is said, so nothing else is relevant. The expected error is [name required], and the log confirms it. The row unverified admin chains two methods: aUser().Admin().Unverified(), because the rule is about the combination. The row two problems shows that errors accumulate: [name required email required].

The first row, valid, is as important as the rest. It proves the default is valid, which every other row relies on. If someone adds a required field to User and the default is not updated, that row fails first, and the failure points to the builder, not to six confusing results.

Value receivers

The methods use value receivers, func (b UserBuilder) Named(n string) UserBuilder, and the builder holds a User by value. Each call copies the builder, changes the copy and returns it. The result is that aUser() can be shared across rows and subtests without one test seeing another's changes. A pointer-receiver builder mutates in place, so a base builder stored in a variable and reused would leak changes between tests. If your struct has slices or maps, a value copy shares their backing storage, and the builder method must copy them (slices.Clone, maps.Clone) before changing them.

Naming the methods

Name methods for what the scenario means, not for the field. Admin() and Unverified() read better than SetRole("admin") and SetVerified(false). Scenario names make the test's intent obvious and let the builder hide representation: if Admin becomes a role list, one method changes and no test does. Keep each method to one concept, so they compose, and add a method only when a second test needs it.

A builder needs a way to produce unique values when tests insert many objects: WithID(n) or an internal counter for emails like [email protected]. Uniqueness is a property of the data set, not of one object, so keep the counter in the test, not in a package global that parallel tests share.

Alternatives

A builder is a good fit when objects are large and variations are many. For smaller needs, Go offers lighter shapes.

A function with a mutator. newUser(t, func(u *User) { u.Admin = true }) builds the default and applies the function. It is shorter to write than a builder type and reads well for one change; for several, the function literals get noisy.

Functional options. newUser(WithAdmin(), WithUnverified()) uses the same option pattern as production constructors. It is the closest to idiomatic Go, and a good choice if the production code already uses options.

A plain struct literal with helper defaults. Copy a package variable validUser and change a field: u := validUser; u.Name = "". Because the struct is copied by value, this is safe for flat structs and is the most readable of all for small cases. It fails for nested slices and maps, which would be shared.

Generated or fuzzed data. For property tests, build the object from generated values, as in property based testing. Builders and generators combine well: the builder supplies a valid base and the generator varies one field.

Pick the lightest one that keeps the table readable. Reaching for a builder type for a three-field struct is overkill.

Persisted objects

A database test needs rows, and the builder can insert them: aUser().Admin().Insert(t, db). Keep insertion as a final step separate from Build, so the same builder serves unit tests that never touch a database. A helper that inserts should register cleanup, and should fail the test on error, using t.Helper() so the failure points at the caller. The transaction approach in rollback tests takes care of removal. Avoid builders that quietly insert dependencies: an order builder that creates a customer, an address and a product behind the scenes makes tests slow and hides what they depend on. Let the test ask for the related rows explicitly, with the builders passing identifiers.

Pitfalls

• A default that is almost valid. A builder default that fails one rule makes every test fail for the wrong reason. Test the default once.
• Too many methods. A builder with sixty methods is a second model of your domain. Add methods as tests need them.
• Hidden randomness. A builder that fills fields with random values produces tests you cannot replay. Use fixed values or a seeded source, as in determinism.
• Coupling to production constructors. If the builder calls the real constructor, it inherits its validation and may refuse to build the invalid object a negative test wants. Build the struct directly.
• A shared builder package that grows. Keep builders next to the tests that use them; share one only when several packages need the same type.

The pattern comes from the Java world, and Go's version is lighter because structs are values and zero values are useful. The language rules that make it work are in the Go specification on assignability, the specification on composite literals, and a broader look at how to lay out tests is in the table-driven tests article.