package gomock

Import Path
	go.uber.org/mock/gomock (on go.dev)

Dependency Relation
	imports 10 packages, and imported by one package


Involved Source Files

	    call.go
	    callset.go
	    controller.go
	
		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`.

	    matchers.go
	    string.go


Code Examples

	
	  {
	  	t := &testing.T{}
	  	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)
	  
	  }
	
	  {
	  	t := &testing.T{}
	  	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)
	  
	  }
	
	  {
	  	t := &testing.T{}
	  	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)
	  
	  }



Package-Level Type Names (total 26, in which 9 are exported)


	/* sort exporteds by:  |  */
	
		Call represents an expected call to a mock.

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

			
				AnyTimes allows the expectation to be called 0 or more times

			
				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.

			
				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.

			
				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.

			
				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.

			
				Return declares the values to be returned by the mocked function 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.

			(*Call) String() string
			
				Times declares the exact number of times a function call is expected to be executed.

			
		
			*Call : expvar.Var
			*Call : fmt.Stringer
			
		
			func (*Call).After(preReq *Call) *Call
			func (*Call).AnyTimes() *Call
			func (*Call).Do(f any) *Call
			func (*Call).DoAndReturn(f any) *Call
			func (*Call).MaxTimes(n int) *Call
			func (*Call).MinTimes(n int) *Call
			func (*Call).Return(rets ...any) *Call
			func (*Call).SetArg(n int, value any) *Call
			func (*Call).Times(n int) *Call
			func (*Controller).RecordCall(receiver any, method string, args ...any) *Call
			func (*Controller).RecordCallWithMethodType(receiver any, method string, methodType reflect.Type, args ...any) *Call
			func go.pact.im/x/clock/mockclock.(*MockClockMockRecorder).Now() *Call
			func go.pact.im/x/clock/mockclock.(*MockClockMockRecorder).Schedule(d, f any) *Call
			func go.pact.im/x/clock/mockclock.(*MockClockMockRecorder).Ticker(d any) *Call
			func go.pact.im/x/clock/mockclock.(*MockClockMockRecorder).Timer(d any) *Call
			func go.pact.im/x/clock/mockclock.(*MockTickerMockRecorder).C() *Call
			func go.pact.im/x/clock/mockclock.(*MockTickerMockRecorder).Reset(d any) *Call
			func go.pact.im/x/clock/mockclock.(*MockTickerMockRecorder).Stop() *Call
			func go.pact.im/x/clock/mockclock.(*MockTimerMockRecorder).C() *Call
			func go.pact.im/x/clock/mockclock.(*MockTimerMockRecorder).Reset(d any) *Call
			func go.pact.im/x/clock/mockclock.(*MockTimerMockRecorder).Stop() *Call
			
		
			func (*Call).After(preReq *Call) *Call
			


	
		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.
		
			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)
			    // ..
			  })
			})

		
			
				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.

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

			
				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.
				
				Note: If you pass a *testing.T into [NewController], you no longer
				need to call ctrl.Finish() in your test methods.

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

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

			
				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.

			
		
			func NewController(t TestReporter, opts ...ControllerOption) *Controller
			func WithContext(ctx context.Context, t TestReporter) (*Controller, context.Context)
		
			func go.pact.im/x/clock/mockclock.NewMockClock(ctrl *Controller) *mockclock.MockClock
			func go.pact.im/x/clock/mockclock.NewMockTicker(ctrl *Controller) *mockclock.MockTicker
			func go.pact.im/x/clock/mockclock.NewMockTimer(ctrl *Controller) *mockclock.MockTimer


	
		ControllerOption configures how a Controller should behave.

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


	
		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.

		
			
				Got is invoked with the received value. The result is used when
				printing the failure message.

		
			 GotFormatterFunc
		
			func GotFormatterAdapter(s GotFormatter, m Matcher) Matcher


	
		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.

		
			
				Got implements GotFormatter.

		
			 GotFormatterFunc : GotFormatter


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

		
			
				Matches returns whether x is a match.

			
				String describes what the matcher matches.

		
			
		
			 Matcher : expvar.Var
			 Matcher : fmt.Stringer
			
		
			func All(ms ...Matcher) Matcher
			func Any() Matcher
			func AnyOf(xs ...any) Matcher
			func AssignableToTypeOf(x any) Matcher
			func Cond[T](fn func(x T) 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
		
			func All(ms ...Matcher) Matcher
			func GotFormatterAdapter(s GotFormatter, m Matcher) Matcher
			func WantFormatter(s fmt.Stringer, m Matcher) Matcher
			


	
		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.

		
			
				String implements fmt.Stringer.

		
			 StringerFunc : expvar.Var
			 StringerFunc : fmt.Stringer
			


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

		
			( TestHelper) Errorf(format string, args ...any)
			( TestHelper) Fatalf(format string, args ...any)
			( TestHelper) Helper()
		
			*testing.B
			*testing.F
			*testing.T
			 testing.TB (interface)
			
		
			 TestHelper : TestReporter
			
		
			


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

		
			( TestReporter) Errorf(format string, args ...any)
			( TestReporter) Fatalf(format string, args ...any)
		
			 TestHelper (interface)
			*go.uber.org/zap.SugaredLogger
			 google.golang.org/grpc/grpclog.DepthLoggerV2 (interface)
			 google.golang.org/grpc/grpclog.LoggerV2 (interface)
			 google.golang.org/grpc/internal/grpclog.LoggerV2 (interface)
			*testing.B
			*testing.F
			*testing.T
			 testing.TB (interface)
			
		
			
		
			func NewController(t TestReporter, opts ...ControllerOption) *Controller
			func WithContext(ctx context.Context, t TestReporter) (*Controller, context.Context)
			


	


Package-Level Functions (total 29, in which 17 are exported)


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


	
		Any returns a matcher that always matches.


	
		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


	
		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


	

		Type Parameters:
			T: any

		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 int){return x == 1}).Matches(1) // returns true
			Cond(func(x int){return x == 2}).Matches(1) // returns false


	
		Eq returns a matcher that matches on equality.
		
		Example usage:
		
			Eq(5).Matches(5) // returns true
			Eq(5).Matches(4) // returns false


	
		GotFormatterAdapter attaches a GotFormatter to a 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


	
		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.


	
		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.


	
		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.


	
		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


	
		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


	
		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


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


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


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