Mockery

A code generator for Go that turns interfaces into mock implementations using testify/mock. The standard tool for unit-testing layered Go services where every layer is interface-shaped.

How it works

You write an interface:

type Services interface {
    GetUser(ctx context.Context, id string) (*User, error)
}

Run mockery --name=Services --output=mocks and get a MockServices struct that satisfies the interface and lets you set per-call expectations:

m := mocks.NewMockServices(t)
m.EXPECT().
    GetUser(mock.Anything, "u-1").
    Return(&User{ID: "u-1"}, nil).
    Once()

Tests against handlers/services then inject m instead of the real implementation. No DB, no HTTP, fast, deterministic.

Configuration

.mockery.yaml at the repo root drives generation across the whole tree — usually one block per package:

with-expecter: true
packages:
  github.com/me/app/services:
    interfaces:
      Services:
  github.com/me/app/repo:
    interfaces:
      Repository:

Re-run on go generate ./... or as a CI step before go test. Most teams gitignore the mocks/ output and regenerate; some commit it for reproducibility.

Why it’s load-bearing for go-layered-architecture

The whole point of the interfaces-everywhere discipline in the 3-layer pattern is testability. Without a mock generator, you’d hand-write one mock struct per interface — tedious, drift-prone, and the discipline collapses on the first deadline.

Mockery makes the interface contract the source of truth. Change the interface, regenerate, broken tests show up immediately.

Alternatives

Tool	Notes
mockery	Default; widest adoption; expectation-based API
gomock (uber)	Google’s official; more strict matchers; v1 deprecated, v2 (`go.uber.org/mock`) is current
Hand-written stubs	Fine for 1-2 interfaces; doesn’t scale
Real implementations + sqlite	Integration test territory, not unit

For new kulify Go services, mockery v2 is the default. gomock works equivalently if the team already uses it.

kulify usage

Not currently used; no kulify Go project has a layered service that would benefit yet.
Becomes relevant if katastar grows a Service layer or if a future kulify Go daemon (e.g., a SB sync side, a Hermes writer) follows go-layered-architecture.