# Moka: A Go Mocking Framework That Puts Type Safety on the Double

> Moka is a Go mocking framework that pairs with Ginkgo or the testing package. It offers strict doubles, typed doubles, and a fail handler model that makes unverified interactions fail loudly.

**gcapizzi/moka** — A Go mocking framework.

- Repository: https://github.com/gcapizzi/moka
- Stars: 50 · Forks: 1
- Language: Go
- License: Apache-2.0
- Published: 2026-08-17 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/gcapizzi-moka

## What Moka Solves and Who It Serves

Moka addresses a specific pain in Go testing: creating test doubles without giving up compile-time interface enforcement. In Go, you often write hand-rolled fakes that implement an interface, but those fakes can drift from the real interface or silently ignore unexpected calls. Moka provides a structured way to define doubles by embedding a Double type and delegating method calls to it. The framework is aimed at developers who use Ginkgo, a behavior-driven development framework, but it also works with the standard testing package if you supply a fail handler. The README makes clear that Moka is not a code generator; you write the double type yourself. That is a deliberate trade-off: you get control over the method signatures, but you pay with boilerplate.

## The Mechanism: Embedding Double and Delegating with Call

Moka's core idea is that a double type embeds moka.Double and delegates every method you want to stub or mock to the embedded instance via the Call method. The README shows a DieDouble that embeds Double and implements Roll by calling d.Call("Roll", times). The Call method returns a slice of return values plus an error. The example ignores the error because the fail handler will stop the test. This design means Moka does not use reflection or code generation to intercept calls. Instead, you explicitly route each method through Call, which gives the framework a chance to match the call against configured interactions. The Double instance can be strict or non-strict, and the strict variant fails the test if a method receives a call that was not previously allowed or expected.

## Getting Running: Setup with Ginkgo and the testing Package

To use Moka, you start with go get github.com/gcapizzi/moka. Then you register a fail handler. For Ginkgo, you call RegisterDoublesFailHandler(Fail) in your test suite setup, alongside RegisterFailHandler(Fail). For the testing package, you provide a function that matches the FailHandler type: func(message string, callerSkip ...int). The README gives a concrete example where the handler calls t.Fatal(message). This fail handler is central to Moka's behavior because it is invoked whenever a strict double receives an unexpected call or a verification fails. The setup is minimal, but note that support for the testing package is not built in; you must write the adapter yourself. That is a small but real friction point.

## Strict Doubles and Typed Doubles: Two Layers of Safety

Moka offers two distinct forms of protection. The first is strict doubles. When you create a double with NewStrictDouble(), any method call that was not explicitly allowed or expected will trigger the fail handler. This catches typos in method names or forgotten stubs. The second layer is typed doubles, created with NewStrictDoubleWithTypeOf(DieDouble{}). A typed double validates that every configured interaction matches a method that actually exists on the type. The README shows a test that tries to allow a call to "Cast" on a DieDouble, and Moka fails with the message: Invalid interaction: type 'DieDouble' has no method 'Cast'. This is a meaningful improvement over string-based mocking frameworks that only fail at runtime when the call never happens. Typed doubles move a class of errors from silent test failure to immediate feedback.

## Allowing, Expecting, and Verifying Interactions

Moka distinguishes between allowing a call and expecting a call. AllowDouble(die).To(ReceiveCallTo("Roll").With(3).AndReturn([]int{1, 2, 3})) sets up a stub that returns a value when called. ExpectDouble(logger).To(ReceiveCallTo("Log").With("[1, 2, 3]")) sets an expectation that the call must happen. After the test body, you call VerifyCalls(logger) to check that all expected calls occurred. This separation is standard in mocking frameworks, but Moka's API is readable and reads like a sentence. The README also mentions AndDo for custom behavior or argument assertions, though the example is truncated. This is useful when you need to perform side effects or validate arguments beyond simple equality.

## A Real Limitation: Interfaces Only and Manual Double Writing

Moka has a hard constraint: it can only replace objects that are accessed through interfaces. The README states this directly: only objects used through interfaces can be replaced by Moka doubles. If your code depends on concrete types, you cannot use Moka to fake them. You would need to refactor your code to introduce interfaces, which may not always be desirable. Another limitation is that you must write every double type by hand. For an interface with many methods, this means a lot of boilerplate. The README even notes that support for the testing package has not been added yet, so you have to write your own fail handler. In a large codebase, this manual effort could outweigh the benefits, especially if you are only using a few doubles.

## Alternative Approaches: Code Generation and Other Frameworks

Moka is not the only mocking framework for Go, and its approach differs significantly from code generators. Tools like mockgen (from the gomock project) generate mock implementations from interface definitions. That removes the manual boilerplate but introduces a code generation step into your build or test workflow. Another alternative is to write hand-rolled fakes without a framework, which gives you full control but no built-in verification or strictness. Moka sits between those: it gives you structured doubles with strictness and typed checks, but it still requires you to write the double type yourself. If you prefer generating mocks to writing them, Moka will feel tedious. If you want a lightweight, explicit way to define doubles without code generation, Moka's model is appealing.

## Conclusion

Adopt Moka if you write Go tests with Ginkgo and want doubles that fail on unconfigured calls, with optional type checking to catch impossible interactions early. Avoid it if you need a mocking library that generates code or supports the testing package out of the box. Before adopting, verify that your collaborators are always accessed through interfaces, since Moka cannot replace concrete types. Also check that the repository is still maintained, as there are no recent releases listed and the last push date is unknown.

## FAQ

### What does Moka mean in the gcapizzi/moka repository?

Nothing to do with the Italian word. Moka is the name of a Go mocking framework, described as a mocking framework for the Go programming language, which works very well with Ginkgo but can be used with any other testing framework including the standard testing package.

### How do I add Moka to a Go project?

With `go get github.com/gcapizzi/moka`. The module targets Go 1.12 and requires Ginkgo 1.8.0 and Gomega 1.5.0, and the project is licensed under Apache-2.0.

### How do I set up Moka with Ginkgo?

Import the moka package and register Ginkgo's Fail function as Moka's doubles fail handler with RegisterDoublesFailHandler, alongside RegisterFailHandler, then call RunSpecs as in any Ginkgo suite.

### Can I use Moka with the standard testing package?

Support has not been added yet, but the documentation says you can still use it. Supply a doubles fail handler of type func(message string, callerSkip ...int), modelled on Ginkgo's Fail, that makes the test fail, for example by calling t.Fatal.

## Sources

- [Official README](https://github.com/gcapizzi/moka#readme)
- [Project repository](https://github.com/gcapizzi/moka)
- [README](https://github.com/gcapizzi/moka/blob/master/README.md)
- [Releases](https://github.com/gcapizzi/moka/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/gcapizzi-moka