• This repository has been archived on 27/Jun/2023
  • Stars
    star
    9,286
  • Rank 3,861 (Top 0.08 %)
  • Language
    Go
  • License
    Apache License 2.0
  • Created over 9 years ago
  • Updated 11 months ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

GoMock is a mocking framework for the Go programming language.

gomock

Update, June 2023: This repo and tool are no longer maintained. Please see go.uber.org/mock for a maintained fork instead.

Build Status Go Reference

gomock is a mocking framework for the Go programming language. It integrates well with Go's built-in testing package, but can be used in other contexts too.

Installation

Once you have installed Go, install the mockgen tool.

Note: If you have not done so already be sure to add $GOPATH/bin to your PATH.

To get the latest released version use:

Go version < 1.16

GO111MODULE=on go get github.com/golang/mock/[email protected]

Go 1.16+

go install github.com/golang/mock/[email protected]

If you use mockgen in your CI pipeline, it may be more appropriate to fixate on a specific mockgen version. You should try to keep the library in sync with the version of mockgen used to generate your mocks.

Running mockgen

mockgen has two modes of operation: source and reflect.

Source mode

Source mode generates mock interfaces from a source file. It is enabled by using the -source flag. Other flags that may be useful in this mode are -imports and -aux_files.

Example:

mockgen -source=foo.go [other options]

Reflect mode

Reflect mode generates mock interfaces by building a program that uses reflection to understand interfaces. It is enabled by passing two non-flag arguments: an import path, and a comma-separated list of symbols.

You can use "." to refer to the current path's package.

Example:

mockgen database/sql/driver Conn,Driver

# Convenient for `go:generate`.
mockgen . Conn,Driver

Flags

The mockgen command is used to generate source code for a mock class given a Go source file containing interfaces to be mocked. It supports the following flags:

  • -source: A file containing interfaces to be mocked.

  • -destination: A file to which to write the resulting source code. If you don't set this, the code is printed to standard output.

  • -package: The package to use for the resulting mock class source code. If you don't set this, the package name is mock_ concatenated with the package of the input file.

  • -imports: A list of explicit imports that should be used in the resulting source code, specified as a comma-separated list of elements of the form foo=bar/baz, where bar/baz is the package being imported and foo is the identifier to use for the package in the generated source code.

  • -aux_files: A list of additional files that should be consulted to resolve e.g. embedded interfaces defined in a different file. This is specified as a comma-separated list of elements of the form foo=bar/baz.go, where bar/baz.go is the source file and foo is the package name of that file used by the -source file.

  • -build_flags: (reflect mode only) Flags passed verbatim to go build.

  • -mock_names: A list of custom names for generated mocks. This is specified as a comma-separated list of elements of the form Repository=MockSensorRepository,Endpoint=MockSensorEndpoint, where Repository is the interface name and MockSensorRepository is the desired mock name (mock factory method and mock recorder will be named after the mock). If one of the interfaces has no custom name specified, then default naming convention will be used.

  • -self_package: The full package import path for the generated code. The purpose of this flag is to prevent import cycles in the generated code by trying to include its own package. This can happen if the mock's package is set to one of its inputs (usually the main one) and the output is stdio so mockgen cannot detect the final output package. Setting this flag will then tell mockgen which import to exclude.

  • -copyright_file: Copyright file used to add copyright header to the resulting source code.

  • -debug_parser: Print out parser results only.

  • -exec_only: (reflect mode) If set, execute this reflection program.

  • -prog_only: (reflect mode) Only generate the reflection program; write it to stdout and exit.

  • -write_package_comment: Writes package documentation comment (godoc) if true. (default true)

For an example of the use of mockgen, see the sample/ directory. In simple cases, you will need only the -source flag.

Building Mocks

type Foo interface {
  Bar(x int) int
}

func SUT(f Foo) {
 // ...
}
func TestFoo(t *testing.T) {
  ctrl := gomock.NewController(t)

  // Assert that Bar() is invoked.
  defer ctrl.Finish()

  m := NewMockFoo(ctrl)

  // Asserts that the first and only call to Bar() is passed 99.
  // Anything else will fail.
  m.
    EXPECT().
    Bar(gomock.Eq(99)).
    Return(101)

  SUT(m)
}

If you are using a Go version of 1.14+, a mockgen version of 1.5.0+, and are passing a *testing.T into gomock.NewController(t) you no longer need to call ctrl.Finish() explicitly. It will be called for you automatically from a self registered Cleanup function.

Building Stubs

type Foo interface {
  Bar(x int) int
}

func SUT(f Foo) {
 // ...
}
func TestFoo(t *testing.T) {
  ctrl := gomock.NewController(t)
  defer ctrl.Finish()

  m := NewMockFoo(ctrl)

  // Does not make any assertions. Executes the anonymous functions and returns
  // its result when Bar is invoked with 99.
  m.
    EXPECT().
    Bar(gomock.Eq(99)).
    DoAndReturn(func(_ int) int {
      time.Sleep(1*time.Second)
      return 101
    }).
    AnyTimes()

  // Does not make any assertions. Returns 103 when Bar is invoked with 101.
  m.
    EXPECT().
    Bar(gomock.Eq(101)).
    Return(103).
    AnyTimes()

  SUT(m)
}

Modifying Failure Messages

When a matcher reports a failure, it prints the received (Got) vs the expected (Want) value.

Got: [3]
Want: is equal to 2
Expected call at user_test.go:33 doesn't match the argument at index 1.
Got: [0 1 1 2 3]
Want: is equal to 1

Modifying Want

The Want value comes from the matcher's String() method. If the matcher's default output doesn't meet your needs, then it can be modified as follows:

gomock.WantFormatter(
  gomock.StringerFunc(func() string { return "is equal to fifteen" }),
  gomock.Eq(15),
)

This modifies the gomock.Eq(15) matcher's output for Want: from is equal to 15 to is equal to fifteen.

Modifying Got

The Got value comes from the object's String() method if it is available. In some cases the output of an object is difficult to read (e.g., []byte) and it would be helpful for the test to print it differently. The following modifies how the Got value is formatted:

gomock.GotFormatterAdapter(
  gomock.GotFormatterFunc(func(i interface{}) string {
    // Leading 0s
    return fmt.Sprintf("%02d", i)
  }),
  gomock.Eq(15),
)

If the received value is 3, then it will be printed as 03.

Debugging Errors

reflect vendoring error

cannot find package "."
... github.com/golang/mock/mockgen/model

If you come across this error while using reflect mode and vendoring dependencies there are three workarounds you can choose from:

  1. Use source mode.
  2. Include an empty import import _ "github.com/golang/mock/mockgen/model".
  3. Add --build_flags=--mod=mod to your mockgen command.

This error is due to changes in default behavior of the go command in more recent versions. More details can be found in #494.

More Repositories

1

go

The Go programming language
Go
121,832
star
2

groupcache

groupcache is a caching and cache-filling library, intended as a replacement for memcached in many cases.
Go
12,859
star
3

dep

Go dependency management tool experiment (deprecated)
Go
12,857
star
4

protobuf

Go support for Google's protocol buffers
Go
9,676
star
5

tools

[mirror] Go Tools
Go
7,321
star
6

mobile

[mirror] Go on Mobile
Go
5,768
star
7

oauth2

Go OAuth2
Go
5,270
star
8

lint

[mirror] This is a linter for Go source code. (deprecated)
Go
3,974
star
9

vscode-go

Go extension for Visual Studio Code
TypeScript
3,810
star
10

glog

Leveled execution logs for Go
Go
3,520
star
11

proposal

Go Project Design Documents
Go
3,312
star
12

crypto

[mirror] Go supplementary cryptography libraries
Go
2,982
star
13

net

[mirror] Go supplementary network libraries
Go
2,846
star
14

example

Go example projects
Go
2,526
star
15

geo

S2 geometry library in Go
Go
1,655
star
16

tour

[mirror] A Tour of Go
Go
1,543
star
17

vgo

[mirror] Versioned Go Prototype
Go
1,519
star
18

snappy

The Snappy compression format in the Go programming language.
Go
1,512
star
19

sys

[mirror] Go packages for low-level interaction with the operating system
Go
1,253
star
20

pkgsite

[mirror] Home of the pkg.go.dev website
Go
1,148
star
21

leveldb

The LevelDB key-value database in the Go programming language.
Go
1,145
star
22

gddo

Go Doc Dot Org
Go
1,104
star
23

gofrontend

Go compiler frontend (gccgo)
Go
852
star
24

sync

[mirror] concurrency primitives
Go
848
star
25

exp

[mirror] Experimental and deprecated packages
Go
838
star
26

freetype

The Freetype font rasterizer in the Go programming language.
Go
783
star
27

text

[mirror] Go text processing support
Go
745
star
28

playground

[mirror] The Go Playground
Go
741
star
29

talks

Go talks
694
star
30

appengine

Go App Engine packages
Go
669
star
31

build

[mirror] Go's continuous build and release infrastructure (no stability promises)
Go
627
star
32

vulndb

[mirror] The Go Vulnerability Database
Go
555
star
33

image

[mirror] Go supplementary image libraries
Go
522
star
34

blog

[mirror] Go Blog (obsolete)
389
star
35

time

[mirror] Go supplementary time packages
Go
383
star
36

vuln

[mirror] the database client and tools for the Go vulnerability database
Go
376
star
37

perf

[mirror] Performance measurement, storage, and analysis.
Go
375
star
38

website

[mirror] Home of the go.dev and golang.org websites
HTML
373
star
39

sublime-build

The official Sublime Text package for Go build system integration.
Python
343
star
40

xerrors

Go
277
star
41

term

Go terminal and console support
Go
272
star
42

debug

[mirror] debugging tools
Go
230
star
43

dl

[mirror] go install golang.org/dl/go1.N@latest
Go
189
star
44

mod

[mirror] Go module mechanics libraries
Go
187
star
45

benchmarks

Benchmarks for the perf dashboard
Go
181
star
46

arch

[mirror] architecture code
Go
145
star
47

review

[mirror] Tool for working with Gerrit code reviews
Go
143
star
48

cwg

Community outreach Working Group
132
star
49

oscar

[mirror] Open source contributor agent architecture repo.
Go
90
star
50

govulncheck-action

[mirror] GitHub action for govulncheck
89
star
51

sublime-config

A library for Go environment configuration in Sublime Text
Python
85
star
52

winstrap

Bootstrapping tools for windows builders
Go
48
star
53

telemetry

[mirror] Go Telemetry services and libraries
Go
36
star
54

wiki

[mirror] Go Wiki
29
star
55

scratch

[mirror] repository used for testing
Go
28
star
56

pkgsite-metrics

Code to serve pkg.go.dev/metrics [mirror]
Go
13
star
57

go-get-issue-15410

go-get-issue-15410
Go
4
star
58

.github

2
star
59

.allstar

2
star