mockaka

README

Mockaka

Motivation

Mockaka is a mock server for GRPC services. It uses generated .pb.go files to implement gRPC service for you. Intended use is end-to-end testing. Unlike GripMock it does not need original proto files and is intended to be used directly from go tests.

Use

Start with creating new mock:

m := mockaka.New(t)

Mocking a gRPC service

Use AddService method with mockaka.Register and RegisterServiceServer function generated by protoc. AddService may be chained for convinience.

m := mockaka.
    New(t).
    AddService(mockaka.Register(spb.RegisterStringsServiceServer), []mockaka.Stub{}).
    AddService(mockaka.Register(spb.RegisterStrongsServiceServer), []mockaka.Stub{}).
    AddService(mockaka.Register(spb.RegisterStonksServiceServer), []mockaka.Stub{})

Creating stubs

There are four ways to create stubs.

• mockaka.NewStub
• mockaka.NewMatchStub
• mockaka.NewErrStub
• mockaka.NewMatchErrStub

Running mock server

Use Run method followed by defered Stop so when test finishes running mock server is stopped and new test can run mock server on same address.

go m.Run(address)
defer m.Stop()

Checking gRPC service response

There are helper functions to check protobuf structs for equality:

• mockaka.PB returns a copy of it's argument with all unexported fields set to zero values.
• mockaka.PBEq is equivalent to require.Equal(t, PB(expected), PB(actual), msgAndArgs...)

Full example

You can find full example in example directory. It contains two services:

• StringsService which can Reverse strings
• StringsCacheService which can also Reverse strings calling StringsService.Reverse. It uses inmemory cache to lower StringsService load. Cache can also be cleared with Invalidate.

StringsService is mocked to test StringsCacheService.

Documentation

Index

• func MatchAny[I protomsg](actual I) int
• func PB[T protomsg](t T) T
• func PBEq[T protomsg](t *testing.T, expected, actual T, msgAndArgs ...any)
• func UnaryMethod[S any, I, O protomsg](m func(S, context.Context, I) (O, error)) string
• type MatchFunc
  • func NewDefaultMatchFunc[I protomsg](expected I) MatchFunc[I]
• type Mock
  • func New(t *testing.T) *Mock
  • func (m *Mock) AddService(reg Reg, stubs []Stub) *Mock
  • func (m *Mock) Run(address string)
  • func (m *Mock) Stop()
• type Reg
  • func Register[ServiceServerType any](registerServerFunc registerServerFunc[ServiceServerType]) Reg
• type Stub
  • func NewErrStub[I, O protomsg](method string, request I, err error) Stub
  • func NewMatchErrStub[I, O protomsg](method string, requestMatchFunc MatchFunc[I], err error) Stub
  • func NewMatchStub[I, O protomsg](method string, requestMatchFunc MatchFunc[I], response O) Stub
  • func NewStub[I, O protomsg](method string, request I, response O) Stub

Functions

func MatchAny

func MatchAny[I protomsg](actual I) int

MatchAny is a special matcher that matches any request.

func PB

func PB[T protomsg](t T) T

PB prepares protobuf struct for comparison. It returns a copy of it's argument with all unexported fields set to zero values.

func PBEq

func PBEq[T protomsg](t *testing.T, expected, actual T, msgAndArgs ...any)

PBEq is equivalent to require.Equal for protobuf structs. It only compares exported fields unlike require.Equal.

func UnaryMethod

func UnaryMethod[S any, I, O protomsg](m func(S, context.Context, I) (O, error)) string

UnaryMethod gets rpc call's name. Use like this: mockaka.UnaryMethod(pb.ServiceServer.Method).

Types

type MatchFunc

type MatchFunc[I protomsg] func(actual I) int

MatchFunc is a function that matches stubs for request. Return value of zero means full match.

func NewDefaultMatchFunc

func NewDefaultMatchFunc[I protomsg](expected I) MatchFunc[I]

NewDefaultMatchFunc returns default match function.

type Mock

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

Mock is a mock server. Use New to instantiate.

func New

func New(t *testing.T) *Mock

New creates new mock server. Use AddService for setup and Run to start listening.

func (*Mock) AddService

func (m *Mock) AddService(reg Reg, stubs []Stub) *Mock

AddService adds new service with stubs. First argument is mockaka.Register(pb.ServiceServer).

func (*Mock) Run

func (m *Mock) Run(address string)

Run mock server using provided stubs. Run blocks until mock server is ready.

func (*Mock) Stop

func (m *Mock) Stop()

Stop mock service.

type Reg

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

Reg is a processed representation of RegisterServiceServer function generated by protoc.

func Register

func Register[ServiceServerType any](registerServerFunc registerServerFunc[ServiceServerType]) Reg

Register creates Reg from RegisterServiceServer function.

type Stub

type Stub interface {
	Times(n int) Stub
	Name(name string) Stub
	// contains filtered or unexported methods
}

Stub contains request or matcher and corresponding response.

func NewErrStub

func NewErrStub[I, O protomsg](method string, request I, err error) Stub

NewErrStub creates new stub that will return an error. It will be used if request matches exactly. NewErrStub demands explicit type parameters.

func NewMatchErrStub

func NewMatchErrStub[I, O protomsg](method string, requestMatchFunc MatchFunc[I], err error) Stub

NewMatchErrStub creates a new stub that will return an error. It uses provided MatchFunc for matching. NewMatchErrStub demands explicit type parameters.

func NewMatchStub

func NewMatchStub[I, O protomsg](method string, requestMatchFunc MatchFunc[I], response O) Stub

NewMatchStub creates a new stub using provided MatchFunc.

func NewStub

func NewStub[I, O protomsg](method string, request I, response O) Stub

NewStub creates new stub. It will be used if request matches exactly.