gomock

Documentation

Overview

Package gomock is a mock framework for Go.

Standard usage:

(1) Define an interface that you wish to mock.
      type MyInterface interface {
        SomeMethod(x int64, y string)
      }
(2) Use mockgen to generate a mock from the interface.
(3) Use the mock in a test:
      func TestMyThing(t *testing.T) {
        mockCtrl := gomock.NewController(t)
        mockObj := something.NewMockMyInterface(mockCtrl)
        mockObj.EXPECT().SomeMethod(4, "blah")
        // pass mockObj to a real object and play with it.
      }

By default, expected calls are not enforced to run in any particular order. Call order dependency can be enforced by use of InOrder and/or Call.After. Call.After can create more varied call order dependencies, but InOrder is often more convenient.

The following examples create equivalent call order dependencies.

Example of using Call.After to chain expected call order:

firstCall := mockObj.EXPECT().SomeMethod(1, "first")
secondCall := mockObj.EXPECT().SomeMethod(2, "second").After(firstCall)
mockObj.EXPECT().SomeMethod(3, "third").After(secondCall)

Example of using InOrder to declare expected call order:

gomock.InOrder(
    mockObj.EXPECT().SomeMethod(1, "first"),
    mockObj.EXPECT().SomeMethod(2, "second"),
    mockObj.EXPECT().SomeMethod(3, "third"),
)

The standard TestReporter most users will pass to `NewController` is a `*testing.T` from the context of the test. Note that this will use the standard `t.Error` and `t.Fatal` methods to report what happened in the test. In some cases this can leave your testing package in a weird state if global state is used since `t.Fatal` is like calling panic in the middle of a function. In these cases it is recommended that you pass in your own `TestReporter`.

Index

• func InOrder(args ...any)
• func WithOverridableExpectations() overridableExpectationsOption
• type Call
  • func (c *Call) After(preReq *Call) *Call
  • func (c *Call) AnyTimes() *Call
  • func (c *Call) Do(f any) *Call
  • func (c *Call) DoAndReturn(f any) *Call
  • func (c *Call) MaxTimes(n int) *Call
  • func (c *Call) MinTimes(n int) *Call
  • func (c *Call) Return(rets ...any) *Call
  • func (c *Call) SetArg(n int, value any) *Call
  • func (c *Call) String() string
  • func (c *Call) Times(n int) *Call
• type Controller
  • func NewController(t TestReporter, opts ...ControllerOption) *Controller
  • func WithContext(ctx context.Context, t TestReporter) (*Controller, context.Context)
  • func (ctrl *Controller) Call(receiver any, method string, args ...any) []any
  • func (ctrl *Controller) Finish()
  • func (ctrl *Controller) RecordCall(receiver any, method string, args ...any) *Call
  • func (ctrl *Controller) RecordCallWithMethodType(receiver any, method string, methodType reflect.Type, args ...any) *Call
  • func (ctrl *Controller) Satisfied() bool
• type ControllerOption
• type GotFormatter
• type GotFormatterFunc
  • func (f GotFormatterFunc) Got(got any) string
• type Matcher
  • func All(ms ...Matcher) Matcher
  • func Any() Matcher
  • func AnyOf(xs ...any) Matcher
  • func AssignableToTypeOf(x any) Matcher
  • func Cond(fn func(x any) bool) Matcher
  • func Eq(x any) Matcher
  • func GotFormatterAdapter(s GotFormatter, m Matcher) Matcher
  • func InAnyOrder(x any) Matcher
  • func Len(i int) Matcher
  • func Nil() Matcher
  • func Not(x any) Matcher
  • func Regex(regexStr string) Matcher
  • func WantFormatter(s fmt.Stringer, m Matcher) Matcher
• type StringerFunc
  • func (f StringerFunc) String() string
• type TestHelper
• type TestReporter

Examples

• Call.DoAndReturn (CaptureArguments)
• Call.DoAndReturn (Latency)
• Call.DoAndReturn (WithOverridableExpectations)

Functions

func InOrder

func InOrder(args ...any)

InOrder declares that the given calls should occur in order. It panics if the type of any of the arguments isn't *Call or a generated mock with an embedded *Call.

func WithOverridableExpectations

func WithOverridableExpectations() overridableExpectationsOption

WithOverridableExpectations allows for overridable call expectations i.e., subsequent call expectations override existing call expectations

Types

type Call

type Call struct {
	// contains filtered or unexported fields
}

Call represents an expected call to a mock.

func (*Call) After

func (c *Call) After(preReq *Call) *Call

After declares that the call may only match after preReq has been exhausted.

func (*Call) AnyTimes

func (c *Call) AnyTimes() *Call

AnyTimes allows the expectation to be called 0 or more times

func (*Call) Do

func (c *Call) Do(f any) *Call

Do declares the action to run when the call is matched. The function's return values are ignored to retain backward compatibility. To use the return values call DoAndReturn. It takes an any argument to support n-arity functions. The anonymous function must match the function signature mocked method.

func (*Call) DoAndReturn

func (c *Call) DoAndReturn(f any) *Call

DoAndReturn declares the action to run when the call is matched. The return values from this function are returned by the mocked function. It takes an any argument to support n-arity functions. The anonymous function must match the function signature mocked method.

Example (CaptureArguments)

t := &testing.T{} // provided by test
ctrl := gomock.NewController(t)
mockIndex := NewMockFoo(ctrl)
var s string

mockIndex.EXPECT().Bar(gomock.AssignableToTypeOf(s)).DoAndReturn(
	func(arg string) any {
		s = arg
		return "I'm sleepy"
	},
)

r := mockIndex.Bar("foo")
fmt.Printf("%s %s", r, s)

Output:

I'm sleepy foo

Example (Latency)

t := &testing.T{} // provided by test
ctrl := gomock.NewController(t)
mockIndex := NewMockFoo(ctrl)

mockIndex.EXPECT().Bar(gomock.Any()).DoAndReturn(
	func(arg string) string {
		time.Sleep(1 * time.Millisecond)
		return "I'm sleepy"
	},
)

r := mockIndex.Bar("foo")
fmt.Println(r)

Output:

I'm sleepy

Example (WithOverridableExpectations)

t := &testing.T{} // provided by test
ctrl := gomock.NewController(t, gomock.WithOverridableExpectations())
mockIndex := NewMockFoo(ctrl)
var s string

mockIndex.EXPECT().Bar(gomock.AssignableToTypeOf(s)).DoAndReturn(
	func(arg string) any {
		s = arg
		return "I'm sleepy"
	},
)

r := mockIndex.Bar("foo")
fmt.Printf("%s %s", r, s)

Output:

I'm sleepy foo

func (*Call) MaxTimes

func (c *Call) MaxTimes(n int) *Call

MaxTimes limits the number of calls to n times. If AnyTimes or MinTimes have not been called or if MinTimes was previously called with 1, MaxTimes also sets the minimum number of calls to 0.

func (*Call) MinTimes

func (c *Call) MinTimes(n int) *Call

MinTimes requires the call to occur at least n times. If AnyTimes or MaxTimes have not been called or if MaxTimes was previously called with 1, MinTimes also sets the maximum number of calls to infinity.

func (*Call) Return

func (c *Call) Return(rets ...any) *Call

Return declares the values to be returned by the mocked function call.

func (*Call) SetArg

func (c *Call) SetArg(n int, value any) *Call

SetArg declares an action that will set the nth argument's value, indirected through a pointer. Or, in the case of a slice and map, SetArg will copy value's elements/key-value pairs into the nth argument.

func (*Call) String

func (c *Call) String() string

func (*Call) Times

func (c *Call) Times(n int) *Call

Times declares the exact number of times a function call is expected to be executed.

type Controller

type Controller struct {
	// T should only be called within a generated mock. It is not intended to
	// be used in user code and may be changed in future versions. T is the
	// TestReporter passed in when creating the Controller via NewController.
	// If the TestReporter does not implement a TestHelper it will be wrapped
	// with a nopTestHelper.
	T TestHelper
	// contains filtered or unexported fields
}

A Controller represents the top-level control of a mock ecosystem. It defines the scope and lifetime of mock objects, as well as their expectations. It is safe to call Controller's methods from multiple goroutines. Each test should create a new Controller and invoke Finish via defer.

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

func TestBar(t *testing.T) {
  t.Run("Sub-Test-1", st) {
    ctrl := gomock.NewController(st)
    // ..
  })
  t.Run("Sub-Test-2", st) {
    ctrl := gomock.NewController(st)
    // ..
  })
})

func NewController

func NewController(t TestReporter, opts ...ControllerOption) *Controller

NewController returns a new Controller. It is the preferred way to create a Controller.

Passing *testing.T registers cleanup function to automatically call Controller.Finish when the test and all its subtests complete.

func WithContext

func WithContext(ctx context.Context, t TestReporter) (*Controller, context.Context)

WithContext returns a new Controller and a Context, which is cancelled on any fatal failure.

func (*Controller) Call

func (ctrl *Controller) Call(receiver any, method string, args ...any) []any

Call is called by a mock. It should not be called by user code.

func (*Controller) Finish

func (ctrl *Controller) Finish()

Finish checks to see if all the methods that were expected to be called were called. It is not idempotent and therefore can only be invoked once.

func (*Controller) RecordCall

func (ctrl *Controller) RecordCall(receiver any, method string, args ...any) *Call

RecordCall is called by a mock. It should not be called by user code.

func (*Controller) RecordCallWithMethodType

func (ctrl *Controller) RecordCallWithMethodType(receiver any, method string, methodType reflect.Type, args ...any) *Call

RecordCallWithMethodType is called by a mock. It should not be called by user code.

func (*Controller) Satisfied

func (ctrl *Controller) Satisfied() bool

Satisfied returns whether all expected calls bound to this Controller have been satisfied. Calling Finish is then guaranteed to not fail due to missing calls.

type ControllerOption

type ControllerOption interface {
	// contains filtered or unexported methods
}

ControllerOption configures how a Controller should behave.

type GotFormatter

type GotFormatter interface {
	// Got is invoked with the received value. The result is used when
	// printing the failure message.
	Got(got any) string
}

GotFormatter is used to better print failure messages. If a matcher implements GotFormatter, it will use the result from Got when printing the failure message.

type GotFormatterFunc

type GotFormatterFunc func(got any) string

GotFormatterFunc type is an adapter to allow the use of ordinary functions as a GotFormatter. If f is a function with the appropriate signature, GotFormatterFunc(f) is a GotFormatter that calls f.

func (GotFormatterFunc) Got

func (f GotFormatterFunc) Got(got any) string

Got implements GotFormatter.

type Matcher

type Matcher interface {
	// Matches returns whether x is a match.
	Matches(x any) bool

	// String describes what the matcher matches.
	String() string
}

A Matcher is a representation of a class of values. It is used to represent the valid or expected arguments to a mocked method.

func All

func All(ms ...Matcher) Matcher

All returns a composite Matcher that returns true if and only all of the matchers return true.

func Any

func Any() Matcher

Any returns a matcher that always matches.

func AnyOf

func AnyOf(xs ...any) Matcher

AnyOf returns a composite Matcher that returns true if at least one of the matchers returns true.

Example usage:

AnyOf(1, 2, 3).Matches(2) // returns true
AnyOf(1, 2, 3).Matches(10) // returns false
AnyOf(Nil(), Len(2)).Matches(nil) // returns true
AnyOf(Nil(), Len(2)).Matches("hi") // returns true
AnyOf(Nil(), Len(2)).Matches("hello") // returns false

func AssignableToTypeOf

func AssignableToTypeOf(x any) Matcher

AssignableToTypeOf is a Matcher that matches if the parameter to the mock function is assignable to the type of the parameter to this function.

Example usage:

var s fmt.Stringer = &bytes.Buffer{}
AssignableToTypeOf(s).Matches(time.Second) // returns true
AssignableToTypeOf(s).Matches(99) // returns false

var ctx = reflect.TypeOf((*context.Context)(nil)).Elem()
AssignableToTypeOf(ctx).Matches(context.Background()) // returns true

func Cond

func Cond(fn func(x any) bool) Matcher

Cond returns a matcher that matches when the given function returns true after passing it the parameter to the mock function. This is particularly useful in case you want to match over a field of a custom struct, or dynamic logic.

Example usage:

Cond(func(x any){return x.(int) == 1}).Matches(1) // returns true
Cond(func(x any){return x.(int) == 2}).Matches(1) // returns false

func Eq

func Eq(x any) Matcher

Eq returns a matcher that matches on equality.

Example usage:

Eq(5).Matches(5) // returns true
Eq(5).Matches(4) // returns false

func GotFormatterAdapter

func GotFormatterAdapter(s GotFormatter, m Matcher) Matcher

GotFormatterAdapter attaches a GotFormatter to a Matcher.

func InAnyOrder

func InAnyOrder(x any) Matcher

InAnyOrder is a Matcher that returns true for collections of the same elements ignoring the order.

Example usage:

InAnyOrder([]int{1, 2, 3}).Matches([]int{1, 3, 2}) // returns true
InAnyOrder([]int{1, 2, 3}).Matches([]int{1, 2}) // returns false

func Len

func Len(i int) Matcher

Len returns a matcher that matches on length. This matcher returns false if is compared to a type that is not an array, chan, map, slice, or string.

func Nil

func Nil() Matcher

Nil returns a matcher that matches if the received value is nil.

Example usage:

var x *bytes.Buffer
Nil().Matches(x) // returns true
x = &bytes.Buffer{}
Nil().Matches(x) // returns false

func Not

func Not(x any) Matcher

Not reverses the results of its given child matcher.

Example usage:

Not(Eq(5)).Matches(4) // returns true
Not(Eq(5)).Matches(5) // returns false

func Regex

func Regex(regexStr string) Matcher

Regex checks whether parameter matches the associated regex.

Example usage:

Regex("[0-9]{2}:[0-9]{2}").Matches("23:02") // returns true
Regex("[0-9]{2}:[0-9]{2}").Matches([]byte{'2', '3', ':', '0', '2'}) // returns true
Regex("[0-9]{2}:[0-9]{2}").Matches("hello world") // returns false
Regex("[0-9]{2}").Matches(21) // returns false as it's not a valid type

func WantFormatter

func WantFormatter(s fmt.Stringer, m Matcher) Matcher

WantFormatter modifies the given Matcher's String() method to the given Stringer. This allows for control on how the "Want" is formatted when printing .

type StringerFunc

type StringerFunc func() string

StringerFunc type is an adapter to allow the use of ordinary functions as a Stringer. If f is a function with the appropriate signature, StringerFunc(f) is a Stringer that calls f.

func (StringerFunc) String

func (f StringerFunc) String() string

String implements fmt.Stringer.

type TestHelper

type TestHelper interface {
	TestReporter
	Helper()
}

TestHelper is a TestReporter that has the Helper method. It is satisfied by the standard library's *testing.T.

type TestReporter

type TestReporter interface {
	Errorf(format string, args ...any)
	Fatalf(format string, args ...any)
}

A TestReporter is something that can be used to report test failures. It is satisfied by the standard library's *testing.T.