Mockery (Go)

This document defines how we use Mockery to generate and maintain mocks for Go interfaces.

Policy

  • Mockery is the default tool for mocks in Go.
  • Prefer Mockery-generated mocks over handcrafted mocks or other mocking tools.
  • Exceptions are allowed only with a documented justification in the PR or the owning package README.

When to Use

  • Use Mockery for unit tests that need to isolate a dependency behind a Go interface.
  • Prefer fakes/stubs for simple cases (return canned data with minimal setup).
  • Use mocks when the test must verify interactions (calls, arguments, order).

Rationale

  • Faster to create and update than handcrafted mocks.
  • Reduces interface drift because regeneration is quick when interfaces change.
  • Keeps test assumptions in tests rather than embedded in hand-written mock logic.
  • We often use mocks as stubs; Mockery supports that without extra tooling.

Installation

  • Prefer brew for local installation.
  • If the repo pins a specific version, ensure the installed version matches.
  • If a non-brew install is required (e.g., CI), document it in the repo.

Configuration

  • Use .mockery.yaml in the module root when available. This file is the source of truth for what gets generated.
  • Treat Mockery usage as config-driven and curated (not ad-hoc CLI usage).
  • Keep output paths stable and consistent across packages.

Usage

Run Mockery using the config in .mockery.yaml (no flags):

mockery

Note: run from the repo root so paths in .mockery.yaml resolve correctly.

Operational expectations:

  • We generate only the interfaces and packages explicitly listed in .mockery.yaml.
  • Output locations are standardized (typically under testing/mockery/... or testing/mocks/...).
  • Formatting is consistent and enforced by the config (e.g., goimports).
  • Recursion is opt-in per package when configured.

Conventions

  • Place generated mocks in the locations defined by .mockery.yaml (typically under testing/mockery/...).
  • Commit generated mocks to version control.
  • Regenerate mocks whenever the interface changes.
  • Do not hand-edit generated mocks.

Review Checklist

  • Mocks regenerated after interface changes.
  • Generated code is committed.
  • Tests pass using the updated mocks.

References