grpcstub

README

grpcstub

grpcstub provides gRPC server and client conn ( *grpc.ClientConn ) for stubbing, for testing in Go.

There is an HTTP version stubbing tool with the same design concept, httpstub.

Usage

package myapp

import (
	"io"
	"net/http"
	"testing"

	"github.com/k1LoW/grpcstub"
	"github.com/k1LoW/myapp/protobuf/gen/go/routeguide"
)

func TestClient(t *testing.T) {
	ctx := context.Background()
	ts := grpcstub.NewServer(t, "path/to/protobuf")
	t.Cleanup(func() {
		ts.Close()
	})
	ts.Method("GetFeature").Response(&routeguite.Feature{
		Name: "hello",
		Location: &routeguide.Point{
			Latitude:  10,
			Longitude: 13,
		},
	})
	// OR
	// ts.Method("GetFeature").Response(map[string]any{"name": "hello", "location": map[string]any{"latitude": 10, "longitude": 13}})

	client := routeguide.NewRouteGuideClient(ts.Conn())
	if _, err := client.GetFeature(ctx, &routeguide.Point{
		Latitude:  10,
		Longitude: 13,
	}); err != nil {
		t.Fatal(err)
	}
	{
		got := len(ts.Requests())
		if want := 1; got != want {
			t.Errorf("got %v\nwant %v", got, want)
		}
	}
	req := ts.Requests()[0]
	{
		got := int32(req.Message["longitude"].(float64))
		if want := int32(13); got != want {
			t.Errorf("got %v\nwant %v", got, want)
		}
	}
}

Dynamic Response

grpcstub can return responses dynamically using the protocol buffer schema.

Dynamic response to all requests

ts := grpcstub.NewServer(t, "path/to/protobuf")
t.Cleanup(func() {
	ts.Close()
})
ts.ResponseDynamic()

Dynamic response to a request to a specific method (rpc)

ts := grpcstub.NewServer(t, "path/to/protobuf")
t.Cleanup(func() {
	ts.Close()
})
ts.Service("routeguide.RouteGuide").Method("GetFeature").ResponseDynamic()

Dynamic response with your own generators

ts := grpcstub.NewServer(t, "path/to/protobuf")
t.Cleanup(func() {
	ts.Close()
})
fk := faker.New()
want := time.Now()
opts := []GeneratorOption{
	Generator("*_id", func(req *grpcstub.Request) any {
		return fk.UUID().V4()
	}),
	Generator("*_time", func(req *grpcstub.Request) any {
		return want
	}),
}
ts.ResponseDynamic(opts...)

Test data

• https://github.com/grpc/grpc-go/blob/master/examples/route_guide/routeguide/route_guide.proto

References

• monlabs/grpc-mock: Run a gRPC mock server by using protobuf reflection.

Documentation

Index

• Constants
• func UnmarshalProtoMessage(m Message, pm protoreflect.ProtoMessage) error
• type GenerateFunc
• type GeneratorOption
  • func Generator(pattern string, fn GenerateFunc) GeneratorOption
• type Message
  • func MarshalProtoMessage(pm protoreflect.ProtoMessage) (Message, error)
• type Option
  • func BufConfig(configs ...string) Option
  • func BufDir(dirs ...string) Option
  • func BufLock(locks ...string) Option
  • func BufModule(module string) Option
  • func BufModules(modules []string) Option
  • func DisableReflection() Option
  • func EnableHealthCheck() Option
  • func ImportPath(paths ...string) Option
  • func Proto(protos ...string) Option
  • func UseTLS(cacert, cert, key []byte) Option
• type Request
  • func (req *Request) String() string
• type Response
  • func NewResponse() *Response
• type Server
  • func NewServer(t TB, protopath string, opts ...Option) *Server
  • func NewTLSServer(t TB, protopath string, cacert, cert, key []byte, opts ...Option) *Server
  • func (s *Server) Addr() string
  • func (s *Server) ClearMatchers()
  • func (s *Server) ClearRequests()
  • func (s *Server) ClientConn() *grpc.ClientConn
  • func (s *Server) Close()
  • func (s *Server) Conn() *grpc.ClientConn
  • func (s *Server) Match(fn func(req *Request) bool) *matcher
  • func (s *Server) Method(method string) *matcher
  • func (s *Server) Methodf(format string, a ...any) *matcher
  • func (s *Server) Prepend() *Server
  • func (s *Server) Requests() []*Request
  • func (s *Server) ResponseDynamic(opts ...GeneratorOption) *matcher
  • func (s *Server) Service(service string) *matcher
  • func (s *Server) Servicef(format string, a ...any) *matcher
  • func (s *Server) UnmatchedRequests() []*Request
• type TB

Constants

const (
	HealthCheckService_DEFAULT  = "default"
	HealthCheckService_FLAPPING = "flapping"
)

Functions

func UnmarshalProtoMessage

func UnmarshalProtoMessage(m Message, pm protoreflect.ProtoMessage) error

UnmarshalProtoMessage unmarshals Message to [proto.Message].

Types

type GenerateFunc

type GenerateFunc func(req *Request) any

type GeneratorOption

type GeneratorOption func(generators) generators

func Generator

func Generator(pattern string, fn GenerateFunc) GeneratorOption

type Message

type Message map[string]any

func MarshalProtoMessage

func MarshalProtoMessage(pm protoreflect.ProtoMessage) (Message, error)

MarshalProtoMessage marshals [proto.Message] to Message.

type Option

type Option func(*config) error

func BufConfig

func BufConfig(configs ...string) Option

BufConfig use buf.yaml for BSR.

func BufDir

func BufDir(dirs ...string) Option

BufDir use buf directory.

func BufLock

func BufLock(locks ...string) Option

BufLock use buf.lock for BSR.

func BufModule

func BufModule(module string) Option

BufModule use buf modules for BSR.

func BufModules

func BufModules(modules []string) Option

BufModules use buf modules for BSR.

func DisableReflection

func DisableReflection() Option

DisableReflection disable Server Reflection Protocol

func EnableHealthCheck

func EnableHealthCheck() Option

EnableHealthCheck enable grpc.health.v1

func ImportPath

func ImportPath(paths ...string) Option

ImportPath set import paths

func Proto

func Proto(protos ...string) Option

Proto append protos

func UseTLS

func UseTLS(cacert, cert, key []byte) Option

UseTLS enable TLS

type Request

type Request struct {
	Service string
	Method  string
	Headers metadata.MD
	Message Message
}

func (*Request) String

func (req *Request) String() string

type Response

type Response struct {
	Headers  metadata.MD
	Messages []Message
	Trailers metadata.MD
	Status   *status.Status
}

func NewResponse

func NewResponse() *Response

NewResponse returns a new empty response

type Server

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

func NewServer

func NewServer(t TB, protopath string, opts ...Option) *Server

NewServer returns a new server with registered *grpc.Server protopath is a path of .proto files, import path directory or buf directory.

func NewTLSServer

func NewTLSServer(t TB, protopath string, cacert, cert, key []byte, opts ...Option) *Server

NewTLSServer returns a new server with registered secure *grpc.Server

func (*Server) Addr

func (s *Server) Addr() string

Addr returns server listener address

func (*Server) ClearMatchers

func (s *Server) ClearMatchers()

ClearMatchers clear matchers.

func (*Server) ClearRequests

func (s *Server) ClearRequests()

ClearRequests clear requests.

func (*Server) ClientConn

func (s *Server) ClientConn() *grpc.ClientConn

ClientConn is alias of Conn

func (*Server) Close

func (s *Server) Close()

Close shuts down *grpc.Server

func (*Server) Conn

func (s *Server) Conn() *grpc.ClientConn

Conn returns *grpc.ClientConn which connects *grpc.Server.

func (*Server) Match

func (s *Server) Match(fn func(req *Request) bool) *matcher

Match create request matcher with matchFunc (func(req *grpcstub.Request) bool).

func (*Server) Method

func (s *Server) Method(method string) *matcher

Method create request matcher using method.

func (*Server) Methodf

func (s *Server) Methodf(format string, a ...any) *matcher

Methodf create request matcher using sprintf-ed method.

func (*Server) Prepend

func (s *Server) Prepend() *Server

Prepend prepend matcher.

func (*Server) Requests

func (s *Server) Requests() []*Request

Requests returns []*grpcstub.Request received by router.

func (*Server) ResponseDynamic

func (s *Server) ResponseDynamic(opts ...GeneratorOption) *matcher

ResponseDynamic set handler which return dynamic response.

func (*Server) Service

func (s *Server) Service(service string) *matcher

Service create request matcher using service.

func (*Server) Servicef

func (s *Server) Servicef(format string, a ...any) *matcher

Servicef create request matcher using sprintf-ed service.

func (*Server) UnmatchedRequests

func (s *Server) UnmatchedRequests() []*Request

UnmatchedRequests returns []*grpcstub.Request received but not matched by router.

type TB

type TB interface {
	Error(args ...any)
	Errorf(format string, args ...any)
	Fatal(args ...any)
	Fatalf(format string, args ...any)
	Helper()
}