mockey

Mockey provides a wide range of mocking capabilities for Go:

Function and Method Mocking

• Basic: Supports simple, generic, and variadic functions/methods (both value and pointer receivers). Supports hooks.
• Automatic Cleanup: PatchConvey and PatchRun automatically release mocks after each test case.
• Special Cases: GetMethod handles unexported types, unexported methods, and methods in nested structs.
• Advanced:
  • Interface mocking (experimental)
  • Conditional mocking
  • Sequential returns
  • Decorator pattern (execute original function while mocking)
  • Goroutine filtering (include, exclude, or target specific goroutines)
  • Accessing the Mocker object for advanced usage (e.g., counting execution frequency)

Variable Mocking

• Supports mocking regular variables.
• Supports mocking function variables.

To avoid manual defer mocker.UnPatch() calls, use lifecycle management tools that automatically release mocks when the scope ends.

Both tools support nesting; each layer only releases the mocks created within its own scope.

// PatchRun Example
func TestXXX(t *testing.T) {
	PatchRun(func() {
		Mock(Foo).Return("MOCKED-1!").Build()
		res := Foo("anything")
		if res != "MOCKED-1!" { t.Errorf("expected MOCKED-1!, got %s", res) }
	})

	// Mock is automatically released here
	res := Foo("anything")
	if res != "ori:anything" { t.Errorf("expected ori:anything, got %s", res) }
}

Install the latest version of Mockey using go get:

go get github.com/bytedance/mockey@latest

Mockey allows you to mock functions and methods by rewriting function instructions at runtime. This eliminates the need to refactor code to use interfaces for dependency injection.

Important Requirement: You must disable inlining and compiler optimizations during compilation, otherwise the mock will not work.

To mock a function so that it always returns a specific value, use the Mock().Return().Build() chain.

package main

import (
	"fmt"
	"math/rand"

	. "github.com/bytedance/mockey"
)

func main() {
	// mock `rand.Int` to always return 1
	Mock(rand.Int).Return(1).Build() 
	
	fmt.Printf("rand.Int() always returns: %v\n", rand.Int())
}

Since init() functions run before unit tests, standard mocking often fails. To mock a function called within an init() block:

1. Create a new package (e.g., package d) with an init() function that performs the mock. Use an environment variable check (e.g., os.Getenv("ENV") == "CI") to ensure the mock only runs in test environments.
2. In the package you are testing, find the .go file that is first in alphabetical order (dictionary order) and add an import for package d at the very top.
3. Run your tests with the environment variable set (e.g., ENV=CI go test ./...).

There are three ways to mock interface types:

Method 1: Use GetMethod (via instance) Use GetMethod(instance, "MethodName") to retrieve the method from a concrete instance and mock it.

Method 2: Dummy Implementation Create a dummy struct that embeds the interface, mock the method on that dummy type, and then mock the constructor function to return the dummy instance.

Method 3: Interface Mock (Recommended) Use the experimental exp/iface package to mock the interface directly across all implementations.

// Method 1: GetMethod
instance := NewFoo()
Mock(GetMethod(instance, "Foo")).Return("MOCKED!").Build()

// Method 2: Dummy Implementation
type foo struct{FooI}
Mock((*foo).Foo).Return("MOCKED!").Build()
Mock(NewFoo).Return(new(foo)).Build()

Mockey uses a stack-based approach to manage mock lifecycles through PatchConvey and PatchRun.

1. Context Creation: When PatchConvey or PatchRun is called, a new layer (a map of mocks) is pushed onto a global stack (gMocker).
2. Mock Registration: Any mock created via Mock(...).Build() within that context is added to the top-most layer of the stack.
3. Isolation & Nesting: Nested calls to PatchConvey or PatchRun push new layers onto the stack. This allows inner tests to override outer mocks without affecting the outer scope's state once the inner test finishes.
4. Automatic Cleanup: When a PatchConvey or PatchRun block exits, the top layer of the stack is popped, and all mocks in that layer are automatically unpatched.
5. Manual Cleanup: UnPatchAll allows for explicit cleanup of the current scope's mocks.

If you want your mock hook to be able to call the original, un-mocked implementation, use the Origin(funcPtr interface{}) method. This is useful for partial mocking or wrapping the original behavior.

Note: Origin only works when the origin hook is called directly. If the target function is called recursively, it will still hit the mock.

// Example: Wrapping the original function
var originalFun = func(p string) string { return p }

// The mock calls the original with a modification
mockFunc := func(p string) string {
    return originalFun(p + "mocked")
}

mockey.Mock(originalFun).To(mockFunc).Origin(&originalFun).Build()

On Mac M series (arm64), Go versions 1.18.1 through 1.18.5 have a known bug where code may jump to the wrong branch.

Solution: Upgrade your Go version to a version later than 1.18.5.