Test Doubles with Interfaces

A UserService writes rows through *sql.DB directly. Its unit test starts a Postgres container, waits eight seconds for readiness, and fails on laptops where Docker is absent. CI pays the eight seconds on every run, and the test's actual subject — what the service does with a found user, a missing user, or a store that returns a connection error — is buried under infrastructure that proves none of it.

The dependency that hurts is the concrete type in the signature. Replace it with the smallest interface that expresses what the service needs, declared in the service's own package:

package users

type Store interface {
	Get(ctx context.Context, id int64) (User, error)
	Save(ctx context.Context, u User) error
}

type Service struct {
	store Store
}

func NewService(s Store) Service { return Service{store: s} }

Two decisions hide in that shape. The interface belongs to the consumer, not the provider — users.Store is defined where it is used, so the service's contract never bends to what the SQL package happens to export, and swapping implementations requires no changes to either package (interfaces and implicit satisfaction). And the method set is three methods, not the twenty that *sql.DB offers: a narrow interface is a document of what the service actually calls.

Now the test needs no database at all:

type fakeStore struct {
	users map[int64]User
	saved []User
	getErr error
}

func (f *fakeStore) Get(ctx context.Context, id int64) (User, error) {
	if f.getErr != nil {
		return User{}, f.getErr
	}
	u, ok := f.users[id]
	if !ok {
		return User{}, ErrNotFound
	}
	return u, nil
}

func (f *fakeStore) Save(ctx context.Context, u User) error {
	f.saved = append(f.saved, u)
	f.users[u.ID] = u
	return nil
}

func TestService_Profile_Present(t *testing.T) {
	store := &fakeStore{users: map[int64]User{42: {ID: 42, Name: "Ada"}}}
	svc := NewService(store)

	p, err := svc.Profile(context.Background(), 42)
	if err != nil {
		t.Fatalf("Profile: %v", err)
	}
	if p.Name != "Ada" {
		t.Errorf("Name = %q, want Ada", p.Name)
	}
}

This is a fake: it implements the interface with working in-memory logic, so the test exercises the real lookup path rather than a canned response. That distinction matters. A stub returns pre-programmed answers and remembers nothing — right for forcing one branch. A recorder (what mock frameworks call a mock or spy) captures what was called so the test can assert on it — right when the call itself is the behavior. The fake above happens to be both: stateful behavior for the happy path, and a getErr field to stub the failure path. In a moment the assertions need one more piece: the test can set getErr = context.DeadlineExceeded and prove the service propagates timeouts as errors instead of panicking, which is the exact failure error handling warns about.

Some functions exist only for their side effect. Notify(userID, message) returns nothing useful; if it is never called, the feature failed silently, and no amount of inspecting the service's return value reveals it. For those, the test must read the interaction record — which does not require a mocking framework. A struct with function fields is a recorder you can read at a glance:

type mailer struct {
	sent    []Message
	wantErr error
}

func (m *mailer) Send(_ context.Context, msg Message) error {
	if m.wantErr != nil {
		return m.wantErr
	}
	m.sent = append(m.sent, msg)
	return nil
}

func TestService_WelcomeSendsMail(t *testing.T) {
	m := &mailer{}
	svc := NewService(&fakeStore{users: map[int64]User{7: {ID: 7, Email: "ada@example.com"}}}, m)

	if err := svc.Activate(context.Background(), 7); err != nil {
		t.Fatalf("Activate: %v", err)
	}
	if len(m.sent) != 1 {
		t.Fatalf("sent %d messages, want 1", len(m.sent))
	}
	if m.sent[0].To != "ada@example.com" {
		t.Errorf("To = %q, want ada@example.com", m.sent[0].To)
	}
}

Assert the observable outcome first — the message list — and reach for call-order assertions only when order is the contract ("audit log written before the charge"). A test that verifies seven methods were called in sequence encodes the implementation, so every refactor that reorders harmless calls breaks the suite while the feature still works. The rule: verify state and outputs when you can, interactions when the side effect is the entire point.

HTTP dependencies get an in-process server. A client that calls a payment API can be tested without the network by putting the fake on the other end of a real HTTP connection:

func TestPaymentClient_Charges(t *testing.T) {
	var gotAuth, gotPath string
	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		gotAuth = r.Header.Get("Authorization")
		gotPath = r.URL.Path
		w.Header().Set("Content-Type", "application/json")
		fmt.Fprint(w, `{"id":"ch_123","status":"succeeded"}`)
	}))
	defer srv.Close()

	client := NewPaymentClient(srv.URL, "Bearer test-key")
	ch, err := client.Charge(context.Background(), 4999, "tok_visa")
	if err != nil {
		t.Fatalf("Charge: %v", err)
	}
	if ch.ID != "ch_123" {
		t.Errorf("ID = %q, want ch_123", ch.ID)
	}
	if gotAuth != "Bearer test-key" || gotPath != "/v1/charges" {
		t.Errorf("request = %s %s, want POST-style auth and /v1/charges", gotAuth, gotPath)
	}
}

The handler is the recorder: it captures method, path, headers, and body while returning the response the client must parse. httptest binds an ephemeral localhost port, so the test exercises real marshalling, status codes, and error paths — the things a stubbed Doer interface would skip — and tears the server down with defer srv.Close(). Full coverage of handler-side testing arrives with httptest; the point here is that an in-process server replaces both a mock and a staging environment.

The unit suite is fast and green. The service goes to production and deadlocks on its first transaction, because the in-memory fake commits atomically while the real table locks rows under concurrent writes. Nothing was wrong with the tests; the fake had drifted from the thing it stood in for.

This is the standing risk of any test double, and the defenses are specific rather than philosophical.

Give the fake one shared contract with the real implementation. Write the conformance checks once, against the interface, and run them against both:

func TestStoreContract(t *testing.T) {
	t.Run("in-memory", func(t *testing.T) {
		checkStoreContract(t, func() Store { return newFakeStore() })
	})
	t.Run("postgres", func(t *testing.T) {
		if testing.Short() {
			t.Skip("needs a database; skipped with -short")
		}
		checkStoreContract(t, func() Store { return newTestDB(t) })
	})
}

func checkStoreContract(t *testing.T, open func() Store) {
	s := open()
	if err := s.Save(context.Background(), User{ID: 1}); err != nil {
		t.Fatalf("Save: %v", err)
	}
	if _, err := s.Get(context.Background(), 1); err != nil {
		t.Errorf("Get after Save: %v", err)
	}
	if _, err := s.Get(context.Background(), 999); !errors.Is(err, ErrNotFound) {
		t.Errorf("missing id error = %v, want ErrNotFound", err)
	}
}

When the fake stops honoring a documented behavior — a missing row must return ErrNotFound, not a zero value — the contract test fails in milliseconds, before any environment does. The database variant runs behind testing.Short() so the local loop stays fast and CI's full run still executes it.

Keep doubles at the boundary. The service's internal decision logic does not need an interface; test it directly and let it talk to fakes only at genuine edges — storage, network, clock, randomness. Injecting an interface around your own pure function makes the test assert on plumbing you already had coverage for, and each new seam is a place where the test can pass while the wiring is wrong.

Let one layer of reality through. The cheapest honest signal is often a single end-to-end test that runs the real store against a real container once per CI run, while everything above it stays unit-speed. Fakes buy the thousand fast assertions; one integration test keeps them tethered to the world. The same discipline applies when the input to these systems is not handcrafted: the failure you never anticipated is the one fuzzing is built to find.