Master Go Unit Testing with GoMonkey: Stub Functions, Methods, and Globals

GoMonkey is a Go‑language stubbing tool that dynamically replaces functions, methods, and global variables, making unit tests more controllable and stable while keeping the code concise.

Common unit‑testing dilemmas in Go

Functions depend on external HTTP services or databases, preventing isolated execution.

High test coverage but flaky results due to external dependency fluctuations.

Need to verify business logic without caring about actual return values or network responses.

GoMonkey solves these problems by allowing runtime function‑pointer replacement, so tests can control the environment without altering source code.

How GoMonkey works

The core idea is to replace function pointers at the memory level, redirecting calls to custom implementations. The main mechanisms are:

Function replacement : Uses reflect and unsafe to obtain a function’s pointer and patch it.

Method stubbing : Modifies a struct’s method table so method calls point to new logic.

Global variable and interface replacement : Directly changes memory or injects proxies to control behavior.

Think of a function as a robot; GoMonkey is the remote controller that makes the robot perform completely different actions during testing.

Note: GoMonkey is not thread‑safe and may be affected by compiler inlining. Use -gcflags=all=-l to disable inlining during tests.

Installation

go get github.com/agiledragon/gomonkey/v2

Practical examples

Replacing a plain function

Assume a simple addition function:

func Add(a, b int) int {
    return a + b
}

In a test you can force it to always return a fixed value:

patches := gomonkey.ApplyFunc(Add, func(a, b int) int { return 42 })
defer patches.Reset()
fmt.Println(Add(1, 2)) // prints 42

This lets you focus on the surrounding logic without being affected by the actual calculation.

Replacing an external library function (e.g., http.Get )

patches := gomonkey.ApplyFunc(http.Get, func(url string) (*http.Response, error) {
    return &http.Response{StatusCode: 200, Body: ioutil.NopCloser(strings.NewReader("mocked response"))}, nil
})
defer patches.Reset()

By mocking http.Get, tests no longer depend on network availability.

Stubbing a struct method

type Calculator struct{}
func (c *Calculator) Multiply(a, b int) int { return a * b }

patches := gomonkey.ApplyMethod(reflect.TypeOf(&Calculator{}), "Multiply", func(_ *Calculator, a, b int) int { return 100 })
defer patches.Reset()

The Multiply method now always returns 100, simplifying verification of higher‑level logic.

Typical usage scenarios

Function replacement – control return values of ordinary or library functions.

External library replacement – isolate tests from HTTP, database, or other services.

Struct method replacement – test object behavior without invoking real implementations.

Interface method replacement – mock interface implementations while preserving type safety.

Global variable replacement – mock configuration or state that would otherwise affect tests.

Conditional branch control – simulate error paths or edge cases to verify exception handling.

Conclusion

GoMonkey is more than a simple mocking library; it is a powerful instrument for Go unit testing. By allowing developers to replace functions, methods, and globals without touching production code, it enables fully controlled test environments, higher test reliability, and easier maintenance of complex test scenarios.