Quickstart: 'mockgen' Mocking Library

Last modified by chrisby on 2023/10/18 18:17

Introduction

In contrast to run-time mock generation, as seen for example in Java's 'mockito' library, Go uses a unique compile-time strategy. This technique results in the creation of tangible mock files that are directly integrated into the test code. The 'mockgen' library automates this process, providing an efficient means of simulating and handling dependencies during testing. This quick start guide provides a basic introduction of the 'mockgen' library, outlining the necessary steps for initial mock generation and its integration into the test workflow.

Setup

mkdir -p mockgen_example
cd mockgen_example
go mod init example.com/mockgen_example
go get github.com/golang/mock/gomock
go install github.com/golang/mock/mockgen@v1.6.0

The last command installs the 'mockgen' in 'GOPATH', which does the actual mock file generation.

Source Code

First, we need the dependency we want to mock, for this example 'NameProvider.go':

package mockgen_example

//go:generate mockgen -destination=./mock_nameProvider.go -package=mockgen_example . NameProvider

type NameProvider interface {
ProvideName() string
}

Go uses what are called 'build constraints' such as '//go:generate ...' which execute special commands when the application is built. In this case, when 'go generate' is executed, the just installed 'mockgen' command is also executed to create the mock file. The parameters are intuitive: 'destination' defines the path and name of the mock file, 'package' defines the package to address when importing and using the mock file, the dot means the current directory and 'NameProvider' is the type of mock object. Now the mock file can be created by running it:

go generate ./...

The 'mock_nameProvider.go' file should now be generated for the appropriate path and package.

The unit to be tested, 'Greeter', is simple for the sake of an example. It has a dependency of type 'NameProvider' into which the mock object can be injected, and its method 'Greet()' adds a "Hello " before the name provided by the 'NameProvider'. The code for 'Greeter.go' is:

package mockgen_example

type Greeter struct {
nameProvider NameProvider
}

func (n *Greeter) Greet() string {
return "Hello " + n.nameProvider.ProvideName()
}

Finally, here is the test code from 'Greeter_test.go':

package mockgen_example

import (
  "github.com/golang/mock/gomock"
  "testing"
)

func TestGreet(t *testing.T) {
   ctrl := gomock.NewController(t)
   nameProviderMock := NewMockNameProvider(ctrl)
   defer ctrl.Finish()
   greeter := Greeter{nameProviderMock}

   nameProviderMock.EXPECT().ProvideName().Return("John")

   greeting := greeter.Greet()
  if greeting != "Hello John" {
     t.Fail()
   }
}

The first four lines of the test are just to create the mock object and inject it into 'greeter'. Next, the mock can be instructed to behave in a specific way appropriate to the test case, i.e. to simply return "john" when "ProvideName()" is called. Note that the test calls the 'NewMockNameProvider()' method directly from the 'mock_nameProvider.go' file.

Running the Test

go test ./...
# output should look like this:
# ok example.com/mockgen_example 0.001s

Ignore Mock Files in Git

Generated code should not be part of the git history, and should therefore be ignored. Using the mock naming convention from above, a corresponding entry in the '.gitignore' file could be:

**/mock_*.go