mock

GoMock is the mocking framework that popularized the interface-mock-generation pattern in Go. It ships two parts: the gomock runtime package (Controller, Call, Matcher) that test code imports directly to set expectations and assertions, and the mockgen CLI tool that reads an interface definition — either by parsing source (-source) or via reflection on a compiled package — and emits a matching mock implementation as generated Go code. Once mocks are generated, tests use gomock.NewController(t) and a fluent EXPECT().Method(args).Return(value) API to declare expected calls, argument matchers, and return values, with the controller validating that every expectation was satisfied.

As of June 2023 the project is explicitly archived by its maintainers, who point users to go.uber.org/mock as the maintained fork carrying the same API forward. It remains widely referenced in existing Go codebases and is documented here as the original, still-in-use implementation — new projects should evaluate the uber/mock fork for ongoing fixes.

What You Get

• The gomock package — Controller, Call, and Matcher types for declaring and verifying expected method calls in tests
• The mockgen CLI — generates mock implementations from Go interfaces in either source mode (-source) or reflect mode (package + symbol list)
• A fluent expectation API — EXPECT().Method(matchers...).Return(values...) with call-count constraints (Times, MinTimes, MaxTimes, AnyTimes) and ordering (After)
• Built-in argument matchers — Eq, Any, Nil, Not, plus custom matcher support via the Matcher interface
• Automatic cleanup on Go 1.14+ — Controller self-registers via t.Cleanup so ctrl.Finish() doesn’t need to be called explicitly
• Customizable failure output — WantFormatter and GotFormatterAdapter let a test rewrite how expected/actual values are printed on mismatch

Common Use Cases

• Isolating a unit under test from its dependencies by mocking interfaces those dependencies implement
• Generating a mock for a third-party or standard-library interface (e.g. database/sql/driver) via reflect mode without touching that package’s source
• Verifying interaction order and call counts between collaborating components in table-driven tests
• Stubbing return values and side effects (DoAndReturn) to exercise error-handling and edge-case branches
• Wiring mockgen into go:generate directives so mocks regenerate automatically when interfaces change

Under The Hood

Architecture

The module splits into two independently usable pieces sharing one Go module: gomock is the runtime consumed directly by test code (controller.go owns the Controller that tracks a callSet of expected calls keyed by receiver+method, call.go models a single expectation with its matchers and actions, callset.go indexes expected vs. exhausted calls for lookup), while mockgen is a separate main package that never imports gomock at runtime — it only emits code that imports it. mockgen/parse.go builds an interface model either by walking a source AST (go/ast, go/types) in source mode or via mockgen/reflect.go, which compiles and executes a tiny reflection program against the target package in reflect mode; both paths funnel into a shared mockgen/model representation that the generator renders as Go source. This clean separation means the generated mocks have a minimal runtime dependency surface (gomock only) even though generation itself pulls in the full go/types toolchain.

Tech Stack

Pure Go, module github.com/golang/mock, requiring golang.org/x/mod for parsing go.mod in reflect mode and golang.org/x/tools/imports for formatting generated code. No external runtime dependencies beyond the standard library for the gomock package itself; mockgen additionally shells out to go build/go run internally when constructing its reflection program. Distributed as a CLI installed via go install .../mockgen@version and a library imported as github.com/golang/mock/gomock.

Code Quality

Both packages carry substantial table-driven test suites alongside their implementation files (controller_test.go at nearly 1,000 lines, call_test.go, matchers_test.go, mockgen_test.go, parse_test.go), and CI (.github/workflows/test.yaml) runs go vet, a full build, a shell-scripted integration test (ci/test.sh, ci/check_panic_handling.sh), and go test ./... across two Go versions. Error handling favors explicit TestReporter.Fatalf/Errorf calls with descriptive messages pointing at the failing call site rather than swallowing errors, and the code is conventionally formatted with standard Go naming. No linter config or generics-aware type safety beyond what go vet/go build provide, and the project itself states it is no longer maintained, so quality here reflects a frozen snapshot rather than ongoing improvement.

What Makes It Unique

GoMock’s reflect-mode code generation — compiling and executing a throwaway program against the target package to discover interface shapes via go/reflect, rather than only parsing source — let it mock interfaces it had no source access to (including standard-library and third-party interfaces) years before this became a common expectation for Go mocking tools. That said, the pattern is no longer unique to GoMock: its own successor fork carries the identical approach forward, and the project’s current value is chiefly as the long-standing reference implementation many existing codebases still depend on.