Consumer-Side Interfaces

## The problem A service that talks straight to a `*sql.DB` is welded to a database: to run one assertion you need a running server, a schema, fixtures and cleanup. That test is slow, flaky and tells you little about your own logic. What you want is a **seam** — a place where the real collaborator can be lifted out and a stand-in put in, without the code under test knowing the difference. In Go that seam is an interface, and the important part is **who declares it**. ## Step 1 — declare the interface where it is used The package that *calls* the dependency declares the interface, listing only the methods it calls: ```go type UserStore interface { UserByID(ctx context.Context, id int64) (User, error) } ``` This is often one or two methods. It is not a mirror of everything the database layer can do; it is a statement of need. A wide interface makes every stand-in expensive to write, and it drags method signatures — and their imported types — into a package that never uses them. ## Step 2 — take it as a constructor parameter ```go type Service struct{ store UserStore } func NewService(store UserStore) *Service { return &Service{store: store} } ``` The dependency arrives from outside, through the constructor, and is stored in an unexported field. That is what makes substitution possible. If instead the service reaches for a package-level variable, or opens its own connection inside a method, there is nothing for a test to replace and no way to run two cases with different behaviour at the same time. ## Step 3 — satisfy it with a hand-written struct in _test.go ```go type fakeStore struct { user User err error } func (f fakeStore) UserByID(ctx context.Context, id int64) (User, error) { return f.user, f.err } ``` Nothing declares that `fakeStore` implements `UserStore`; it simply has the method, and the compiler accepts it where a `UserStore` is wanted. That is why the real database type also qualifies without being edited or annotated: satisfaction is structural, checked once at compile time against the method set. Putting the fake in a `_test.go` file matters for three reasons. It is compiled only for tests, so it never reaches the production binary. It sits next to the assertions that depend on its behaviour, so a reader sees the whole setup at once. And because it lives in the same package, it can use that package's unexported types freely. ## Using it ```go func TestLookupPropagatesStoreError(t *testing.T) { svc := NewService(fakeStore{err: errNotFound}) if _, err := svc.Lookup(context.Background(), 7); err == nil { t.Fatal("want an error, got nil") } } ``` Each test constructs its own fake with the return values that case needs, so tests share no state and can run in parallel. Adding a case means adding a struct literal, not editing shared setup. ## Why this shape is the Go default Go has no `implements` keyword and no runtime type registry, so an interface costs almost nothing to declare and consumers can declare as many as they like. The idiom that falls out of that is: the *consumer* names the abstraction, the *producer* ships a concrete type. The producing package does not have to anticipate anybody's tests, and two different consumers of the same database type can each describe it in the two methods they care about, differently, without coordinating. It also keeps the dependency direction sane. The service package imports nothing from the database package in order to be testable — the interface is its own declaration — so the test binary for that package pulls in no driver, no connection pool and no network. ## What to watch for A hand-written fake is code, and code can lie. If its method returns the zero value and a `nil` error for every call, every test takes the happy path and the error handling in the service is never executed. Give the fake fields (or function fields) so each test says exactly what the collaborator does, and write at least one case where it fails. Finally, keep the interface where the *use* is. Declaring it in the database package, or in a shared `interfaces` package that everybody imports, recreates the coupling you were trying to remove and makes every change a negotiation.