grpcmock

README

gRPC Test Utilities for Golang

Test gRPC service and client like a pro.

Prerequisites

• Go >= 1.17

Install

go get github.com/nhatthm/grpcmock

Usage

Invoke a gRPC method

Unary Method

package main

import (
	"context"
	"time"

	"github.com/nhatthm/grpcmock"
	"google.golang.org/grpc/test/bufconn"
)

func getItem(l *bufconn.Listener, id int32) (*Item, error) {
	ctx, cancel := context.WithTimeout(context.Background(), time.Millisecond*50)
	defer cancel()

	out := &Item{}
	err := grpcmock.InvokeUnary(ctx, "myservice/GetItem",
		&GetItemRequest{Id: id}, out,
		grpcmock.WithHeader("Locale", "en-US"),
		grpcmock.WithBufConnDialer(l),
		grpcmock.WithInsecure(),
	)

	return out, err
}

Client-Stream Method

package main

import (
	"context"
	"time"

	"github.com/nhatthm/grpcmock"
	"google.golang.org/grpc/test/bufconn"
)

func createItems(l *bufconn.Listener, items []*Item) (*CreateItemsResponse, error) {
	ctx, cancel := context.WithTimeout(context.Background(), time.Millisecond*50)
	defer cancel()

	out := &CreateItemsResponse{}
	err := grpcmock.InvokeClientStream(ctx, "myservice/CreateItems",
		grpcmock.SendAll(items), out,
		grpcmock.WithBufConnDialer(l),
		grpcmock.WithInsecure(),
	)

	return out, err
}

Or with a custom handler

package main

import (
	"context"
	"time"

	"github.com/nhatthm/grpcmock"
	"google.golang.org/grpc"
	"google.golang.org/grpc/test/bufconn"
)

func createItems(l *bufconn.Listener, items []*Item) (*CreateItemsResponse, error) {
	ctx, cancel := context.WithTimeout(context.Background(), time.Millisecond*50)
	defer cancel()

	out := &CreateItemsResponse{}
	err := grpcmock.InvokeClientStream(ctx, "myservice/CreateItems",
		func(stream grpc.ClientStream) error {
			// Handle the stream here.
			return nil
		},
		out,
		grpcmock.WithBufConnDialer(l),
		grpcmock.WithInsecure(),
	)

	return out, err
}

Server-Stream Method

package main

import (
	"context"
	"time"

	"github.com/nhatthm/grpcmock"
	"google.golang.org/grpc/test/bufconn"
)

func listItems(l *bufconn.Listener) ([]*Item, error) {
	ctx, cancel := context.WithTimeout(context.Background(), time.Millisecond*50)
	defer cancel()

	out := make([]*Item, 0)
	err := grpcmock.InvokeServerStream(ctx, "myservice/ListItems",
		&ListItemsRequest{},
		grpcmock.RecvAll(&out),
		grpcmock.WithBufConnDialer(l),
		grpcmock.WithInsecure(),
	)

	return out, err
}

Or with a custom handler

package main

import (
	"context"
	"time"

	"github.com/nhatthm/grpcmock"
	"google.golang.org/grpc"
	"google.golang.org/grpc/test/bufconn"
)

func listItems(l *bufconn.Listener) ([]*Item, error) {
	ctx, cancel := context.WithTimeout(context.Background(), time.Millisecond*50)
	defer cancel()

	out := make([]*Item, 0)
	err := grpcmock.InvokeServerStream(ctx, "myservice/ListItems",
		&ListItemsRequest{},
		func(stream grpc.ClientStream) error {
			// Handle the stream here.
			return nil
		},
		grpcmock.WithBufConnDialer(l),
		grpcmock.WithInsecure(),
	)

	return out, err
}

Bidirectional-Stream Method

package main

import (
	"context"
	"time"

	"github.com/nhatthm/grpcmock"
	"google.golang.org/grpc/test/bufconn"
)

func transformItems(l *bufconn.Listener, in []*Item) ([]*Item, error) {
	ctx, cancel := context.WithTimeout(context.Background(), time.Millisecond*50)
	defer cancel()

	out := make([]*Item, 0)
	err := grpcmock.InvokeBidirectionalStream(ctx, "myservice/TransformItems",
		grpcmock.SendAndRecvAll(in, &out),
		grpcmock.WithBufConnDialer(l),
		grpcmock.WithInsecure(),
	)

	return out, err
}

Or with a custom handler

package main

import (
	"context"
	"time"

	"github.com/nhatthm/grpcmock"
	"google.golang.org/grpc"
	"google.golang.org/grpc/test/bufconn"
)

func transformItems(l *bufconn.Listener, in []*Item) ([]*Item, error) {
	ctx, cancel := context.WithTimeout(context.Background(), time.Millisecond*50)
	defer cancel()

	out := make([]*Item, 0)
	err := grpcmock.InvokeBidirectionalStream(ctx, "myservice/TransformItems",
		func(stream grpc.ClientStream) error {
			// Handle the stream here.
			return nil
		},
		grpcmock.WithBufConnDialer(l),
		grpcmock.WithInsecure(),
	)

	return out, err
}

Donation

If this project help you reduce time to develop, you can give me a cup of coffee :)

Paypal donation

       or scan this

Documentation

Overview

Package grpcmock provides functionalities for testing grpc client and server.

Index

• Constants
• func FromMethodType(t MethodType) (isClientStream bool, isServerStream bool)
• func InvokeBidirectionalStream(ctx context.Context, method string, handle ClientStreamHandler, ...) error
• func InvokeClientStream(ctx context.Context, method string, handle ClientStreamHandler, ...) error
• func InvokeServerStream(ctx context.Context, method string, in interface{}, handle ClientStreamHandler, ...) error
• func InvokeUnary(ctx context.Context, method string, in interface{}, out interface{}, ...) error
• func IsMethodBidirectionalStream(t MethodType) bool
• func IsMethodClientStream(t MethodType) bool
• func IsMethodServerStream(t MethodType) bool
• func IsMethodUnary(t MethodType) bool
• type ClientStreamHandler
  • func RecvAll(out interface{}) ClientStreamHandler
  • func SendAll(in interface{}) ClientStreamHandler
  • func SendAndRecvAll(in interface{}, out interface{}) ClientStreamHandler
  • func (h ClientStreamHandler) Handle(stream grpc.ClientStream) error
• type ContextDialer
• type InvokeOption
  • func WithBufConnDialer(l *bufconn.Listener) InvokeOption
  • func WithCallOptions(opts ...grpc.CallOption) InvokeOption
  • func WithContextDialer(d ContextDialer) InvokeOption
  • func WithDialOptions(opts ...grpc.DialOption) InvokeOption
  • func WithHeader(key, value string) InvokeOption
  • func WithHeaders(header map[string]string) InvokeOption
  • func WithInsecure() InvokeOption
• type MethodType
  • func ToMethodType(isClientStream, isServerStream bool) MethodType
• type ServiceMethod
  • func (m ServiceMethod) FullName() string
• type TestingT

Constants

const (
	// ErrMissingMethod indicates that there is no method in the url.
	ErrMissingMethod err = "missing method"
	// ErrMalformedMethod indicates that the method is malformed.
	ErrMalformedMethod err = "malformed method"
)

Functions

func FromMethodType

func FromMethodType(t MethodType) (isClientStream bool, isServerStream bool)

FromMethodType returns the checks if method type is client stream or server stream.

func InvokeBidirectionalStream

func InvokeBidirectionalStream(
	ctx context.Context,
	method string,
	handle ClientStreamHandler,
	opts ...InvokeOption,
) error

InvokeBidirectionalStream invokes a bidirectional-stream method.

func InvokeClientStream

func InvokeClientStream(
	ctx context.Context,
	method string,
	handle ClientStreamHandler,
	out interface{},
	opts ...InvokeOption,
) error

InvokeClientStream invokes a client-stream method.

func InvokeServerStream

func InvokeServerStream(
	ctx context.Context,
	method string,
	in interface{},
	handle ClientStreamHandler,
	opts ...InvokeOption,
) error

InvokeServerStream invokes a server-stream method.

func InvokeUnary

func InvokeUnary(
	ctx context.Context,
	method string,
	in interface{},
	out interface{},
	opts ...InvokeOption,
) error

InvokeUnary invokes a unary method.

func IsMethodBidirectionalStream

func IsMethodBidirectionalStream(t MethodType) bool

IsMethodBidirectionalStream checks whether the method is client-and-server-stream.

func IsMethodClientStream

func IsMethodClientStream(t MethodType) bool

IsMethodClientStream checks whether the method is client-stream.

func IsMethodServerStream

func IsMethodServerStream(t MethodType) bool

IsMethodServerStream checks whether the method is server-stream.

func IsMethodUnary

func IsMethodUnary(t MethodType) bool

IsMethodUnary checks whether the method is unary.

Types

type ClientStreamHandler

type ClientStreamHandler func(stream grpc.ClientStream) error

ClientStreamHandler handles a client stream.

func RecvAll

func RecvAll(out interface{}) ClientStreamHandler

RecvAll reads everything from the stream and put into the output.

func SendAll

func SendAll(in interface{}) ClientStreamHandler

SendAll sends everything to the stream.

func SendAndRecvAll

func SendAndRecvAll(in interface{}, out interface{}) ClientStreamHandler

SendAndRecvAll sends and receives messages to and from grpc server in turn until server sends the io.EOF.

func (ClientStreamHandler) Handle

func (h ClientStreamHandler) Handle(stream grpc.ClientStream) error

Handle handles a client stream.

type ContextDialer

type ContextDialer = func(context.Context, string) (net.Conn, error)

ContextDialer is to set up the dialer.

type InvokeOption

type InvokeOption func(c *invokeConfig)

InvokeOption sets invoker config.

func WithBufConnDialer

func WithBufConnDialer(l *bufconn.Listener) InvokeOption

WithBufConnDialer sets a *bufconn.Listener as the context dialer.

See:

• grpcmock.WithContextDialer()

func WithCallOptions

func WithCallOptions(opts ...grpc.CallOption) InvokeOption

WithCallOptions sets call options.

func WithContextDialer

func WithContextDialer(d ContextDialer) InvokeOption

WithContextDialer sets a context dialer to create connections.

See:

• grpcmock.WithBufConnDialer()

func WithDialOptions

func WithDialOptions(opts ...grpc.DialOption) InvokeOption

WithDialOptions sets dial options.

func WithHeader

func WithHeader(key, value string) InvokeOption

WithHeader sets request header.

func WithHeaders

func WithHeaders(header map[string]string) InvokeOption

WithHeaders sets request header.

func WithInsecure

func WithInsecure() InvokeOption

WithInsecure disables transport security for the connections.

type MethodType

type MethodType string

MethodType is service method type.

const (
	// MethodTypeUnary indicates that the method is unary.
	MethodTypeUnary MethodType = "Unary"
	// MethodTypeClientStream indicates that the method is client-stream.
	MethodTypeClientStream MethodType = "ClientStream"
	// MethodTypeServerStream indicates that the method is server-stream.
	MethodTypeServerStream MethodType = "ServerStream"
	// MethodTypeBidirectionalStream indicates that the method is bidirectional-stream.
	MethodTypeBidirectionalStream MethodType = "BidirectionalStream"
)

func ToMethodType

func ToMethodType(isClientStream, isServerStream bool) MethodType

ToMethodType defines the method type by checking if it's a client or server strean.

type ServiceMethod

type ServiceMethod struct {
	ServiceName string
	MethodName  string
	MethodType  MethodType
	Input       interface{}
	Output      interface{}
}

ServiceMethod contains description of a grpc service.

func (ServiceMethod) FullName

func (m ServiceMethod) FullName() string

FullName returns the full name of the service method.

type TestingT

type TestingT interface {
	Errorf(format string, args ...interface{})
	FailNow()
	Cleanup(func())
}

TestingT is an interface wrapper around *testing.T.