Categorygo.nhat.io/grpcmock

modulepackage

0.27.0

Repository: https://github.com/nhatthm/grpcmock.git

Documentation: pkg.go.dev

# README

⚠️ From v0.20.0, the project will be rebranded to go.nhat.io/grpcmock. v0.19.0 is the last version with github.com/nhatthm/grpcmock.

gRPC Test Utilities for Golang

Test gRPC service and client like a pro.

Prerequisites
Install
Usage
- Mock a gRPC server
- Invoke a gRPC method

Prerequisites

Go >= 1.21

_{^{[table of contents]}}

Install

go get go.nhat.io/grpcmock

_{^{[table of contents]}}

Usage

Mock a gRPC server

Unary Method

Client-Stream Method

Read more about mocking a Client-Stream Method

package main

import (
	"context"
	"testing"
	"time"

	"github.com/stretchr/testify/assert"
	"go.nhat.io/grpcmock"
	xassert "go.nhat.io/grpcmock/assert"
)

func TestCreateItems(t *testing.T) {
	t.Parallel()

	expected := &CreateItemsResponse{NumItems: 1}

	_, d := grpcmock.MockServerWithBufConn(
		grpcmock.RegisterService(RegisterItemServiceServer),
		func(s *grpcmock.Server) {
			s.ExpectClientStream("myservice/CreateItems").
				WithPayload([]*Item{{Id: 42}}).
				Return(expected)
		},
	)(t)

	ctx, cancel := context.WithTimeout(context.Background(), time.Millisecond*50)
	defer cancel()

	out := &CreateItemsResponse{}
	err := grpcmock.InvokeClientStream(ctx, "myservice/CreateItems",
		grpcmock.SendAll([]*Item{{Id: 42}}), out,
		grpcmock.WithContextDialer(d),
		grpcmock.WithInsecure(),
	)

	xassert.EqualMessage(t, expected, out)
	assert.NoError(t, err)
}

_{^{[table of contents]}}

Server-Stream Method

Read more about mocking a Server-Stream Method

package main

import (
	"context"
	"testing"
	"time"

	"github.com/stretchr/testify/assert"
	"go.nhat.io/grpcmock"
	xassert "go.nhat.io/grpcmock/assert"
)

func TestListItems(t *testing.T) {
	t.Parallel()

	expected := []*Item{
		{Id: 41, Name: "Item 41"},
		{Id: 42, Name: "Item 42"},
	}

	_, d := grpcmock.MockServerWithBufConn(
		grpcmock.RegisterService(RegisterItemServiceServer),
		func(s *grpcmock.Server) {
			s.ExpectServerStream("myservice/ListItems").
				WithPayload(&ListItemsRequest{}).
				Return(expected)
		},
	)(t)

	ctx, cancel := context.WithTimeout(context.Background(), time.Millisecond*50)
	defer cancel()

	actual := make([]*Item, 0)

	err := grpcmock.InvokeServerStream(ctx,
		"myservice/ListItems",
		&ListItemsRequest{},
		grpcmock.RecvAll(&actual),
		grpcmock.WithContextDialer(d),
		grpcmock.WithInsecure(),
	)

	assert.NoError(t, err)
	assert.Len(t, actual, len(expected))

	for i := 0; i < len(expected); i++ {
		xassert.EqualMessage(t, expected[i], actual[i])
	}
}

_{^{[table of contents]}}

Bidirectional-Stream Method

Read more about mocking a Bidirectional-Stream Method

package main

import (
	"context"
	"errors"
	"fmt"
	"io"
	"testing"
	"time"

	"github.com/stretchr/testify/assert"
	"go.nhat.io/grpcmock"
	xassert "go.nhat.io/grpcmock/assert"
	"google.golang.org/grpc"
)

func TestTransformItems(t *testing.T) {
	t.Parallel()

	expected := []*Item{
		{Id: 41, Name: "Item 41"},
		{Id: 42, Name: "Item 42"},
	}

	_, d := grpcmock.MockServerWithBufConn(
		grpcmock.RegisterService(RegisterItemServiceServer),
		func(s *grpcmock.Server) {
			s.ExpectBidirectionalStream("myservice/TransformItems").
				Run(func(ctx context.Context, s grpc.ServerStream) error {
					for {
						item := &Item{}
						err := s.RecvMsg(item)

						if errors.Is(err, io.EOF) {
							return nil
						}

						if err != nil {
							return err
						}

						item.Name = fmt.Sprintf("Modified #%d", item.Id)

						if err := s.SendMsg(item); err != nil {
							return err
						}
					}
				})
		},
	)(t)

	ctx, cancel := context.WithTimeout(context.Background(), time.Millisecond*50)
	defer cancel()

	in := []*Item{
		{Id: 41, Name: "Item 41"},
		{Id: 42, Name: "Item 42"},
	}

	actual := make([]*Item, 0)

	err := grpcmock.InvokeBidirectionalStream(ctx,
		"myservice/TransformItems",
		grpcmock.SendAndRecvAll(in, &actual),
		grpcmock.WithContextDialer(d),
		grpcmock.WithInsecure(),
	)

	assert.NoError(t, err)
	assert.Len(t, actual, len(expected))

	for i := 0; i < len(expected); i++ {
		xassert.EqualMessage(t, expected[i], actual[i])
	}
}

_{^{[table of contents]}}

Invoke a gRPC method

Unary Method

package main

import (
	"context"
	"time"

	"go.nhat.io/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
}

_{^{[table of contents]}}

Client-Stream Method

package main

import (
	"context"
	"time"

	"go.nhat.io/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"

	"go.nhat.io/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(s grpc.ClientStream) error {
			// Handle the stream here.
			return nil
		},
		out,
		grpcmock.WithBufConnDialer(l),
		grpcmock.WithInsecure(),
	)

	return out, err
}

_{^{[table of contents]}}

Server-Stream Method

package main

import (
	"context"
	"time"

	"go.nhat.io/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"

	"go.nhat.io/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(s grpc.ClientStream) error {
			// Handle the stream here.
			return nil
		},
		grpcmock.WithBufConnDialer(l),
		grpcmock.WithInsecure(),
	)

	return out, err
}

_{^{[table of contents]}}

Bidirectional-Stream Method

package main

import (
	"context"
	"time"

	"go.nhat.io/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"

	"go.nhat.io/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(s grpc.ClientStream) error {
			// Handle the stream here.
			return nil
		},
		grpcmock.WithBufConnDialer(l),
		grpcmock.WithInsecure(),
	)

	return out, err
}

_{^{[table of contents]}}

Donation

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

_{^{[table of contents]}}

Paypal donation

or scan this

_{^{[table of contents]}}

# Packages

assert

Package assert provides assertions for grpc.

errors

Package errors provides predefined errors.

format

Package format formats the requests.

invoker

Package invoker constructs a grpc request and executes it.

matcher

Package matcher provides custom matchers for gRPC requests.

mock

No description provided by the author

must

Package must panic on error.

planner

Package planner provides functionalities for deciding what expectation matches the given request.

reflect

Package reflect provides a simple reflection on the grpc server.

request

Package request provides all the expectations for an RPC method.

service

Package service provides service definition.

stream

Package stream provides functions to send or receive messages using a grpc stream.

streamer

Package streamer provides functionalities to work with server-side RPC stream.

test

Package test provides helpers for testing grpcmock.

value

Package value provides functionalities to convert a generic value to string.

# Functions

ChainStreamInterceptor

ChainStreamInterceptor is a wrapper of google.golang.org/grpc.ChainStreamInterceptor().

ChainUnaryInterceptor

ChainUnaryInterceptor is a wrapper of google.golang.org/grpc.ChainUnaryInterceptor().

ConnectionTimeout

ConnectionTimeout is a wrapper of google.golang.org/grpc.ConnectionTimeout().

Creds

Creds is a wrapper of google.golang.org/grpc.Creds().

FindServerMethod

FindServerMethod finds a method in the given server.

InitialConnWindowSize

InitialConnWindowSize is a wrapper of google.golang.org/grpc.InitialConnWindowSize().

InitialWindowSize

InitialWindowSize is a wrapper of google.golang.org/grpc.InitialWindowSize().

InTapHandle

InTapHandle is a wrapper of google.golang.org/grpc.InTapHandle().

InvokeBidirectionalStream

InvokeBidirectionalStream invokes a bidirectional-stream method.

InvokeClientStream

InvokeClientStream invokes a client-stream method.

InvokeServerStream

InvokeServerStream invokes a server-stream method.

InvokeUnary

InvokeUnary invokes a unary method.

KeepaliveEnforcementPolicy

KeepaliveEnforcementPolicy is a wrapper of google.golang.org/grpc.KeepaliveEnforcementPolicy().

KeepaliveParams

KeepaliveParams is a wrapper of google.golang.org/grpc.KeepaliveParams().

MatchClientStreamMsgCount

MatchClientStreamMsgCount matches a number of messages.

MaxConcurrentStreams

MaxConcurrentStreams is a wrapper of google.golang.org/grpc.MaxConcurrentStreams().

MaxHeaderListSize

MaxHeaderListSize is a wrapper of google.golang.org/grpc.MaxHeaderListSize().

MaxRecvMsgSize

MaxRecvMsgSize is a wrapper of google.golang.org/grpc.MaxRecvMsgSize().

MaxSendMsgSize

MaxSendMsgSize is a wrapper of google.golang.org/grpc.MaxSendMsgSize().

MockServer

MockServer starts a new mocked server and ensures all the expectations were met at the end of the test.

MockServerWithBufConn

MockServerWithBufConn starts a new mocked server with bufconn and ensures all the expectations were met at the end of the test.

MockUnstartedServer

MockUnstartedServer mocks the server and ensures all the expectations were met at the end of the test.

NewServer

NewServer creates mocked server.

NewUnstartedServer

NewUnstartedServer returns a new Server but doesn't start it.

NoOpT

NoOpT initiates a new T that does nothing.

ReadBufferSize

ReadBufferSize is a wrapper of google.golang.org/grpc.ReadBufferSize().

RecvAll

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

RegisterService

RegisterService registers a new service using the generated register function.

RegisterServiceFromInstance

RegisterServiceFromInstance registers a new service using the generated server interface.

RegisterServiceFromMethods

RegisterServiceFromMethods registers a new service using service.Method definition.

SendAll

SendAll sends everything to the stream.

SendAndRecvAll

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

StatsHandler

StatsHandler is a wrapper of google.golang.org/grpc.StatsHandler().

StreamInterceptor

StreamInterceptor is a wrapper of google.golang.org/grpc.ChainStreamInterceptor().

UnaryInterceptor

UnaryInterceptor is a wrapper of google.golang.org/grpc.ChainUnaryInterceptor().

UnknownServiceHandler

UnknownServiceHandler is a wrapper of google.golang.org/grpc.UnknownServiceHandler().

WithAddress

WithAddress sets server address.

WithBufConnDialer

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

WithCallOptions

WithCallOptions sets call options.

WithContextDialer

WithContextDialer sets a context dialer to create connections.

WithDialOptions

WithDialOptions sets dial options.

WithHeader

WithHeader sets request header.

WithHeaders

WithHeaders sets request header.

WithInsecure

WithInsecure disables transport security for the connections.

WithListener

WithListener sets the listener.

WithPlanner

WithPlanner sets the expectations' planner.

WithPort

WithPort sets server address port.

WriteBufferSize

WriteBufferSize is a wrapper of google.golang.org/grpc.WriteBufferSize().

# Structs

Server

Server wraps a grpc server and provides mocking functionalities.

# Interfaces

BidirectionalStreamExpectation

BidirectionalStreamExpectation represents the expectation for a client-stream request.

ClientStreamExpectation

ClientStreamExpectation represents the expectation for a client-stream request.

ServerStreamExpectation

ServerStreamExpectation represents the expectation for a server-stream request.

ServerStreamHandler

ServerStreamHandler handles a server-stream request step by step.

T is an interface wrapper around *testing.T.

UnaryExpectation

UnaryExpectation represents the expectation for a unary request.

# Type aliases

ClientStreamHandler

ClientStreamHandler handles a client stream.

ContextDialer

ContextDialer is to set up the dialer.

InvokeOption

InvokeOption sets invoker config.

ServerMocker

ServerMocker is a constructor to create a new mocked server.

ServerMockerWithContextDialer

ServerMockerWithContextDialer starts a new mocked server with a bufconn and returns it as a context dialer for the grpc.DialOption.

ServerOption

ServerOption sets up the mocked server.

# README

gRPC Test Utilities for Golang

Table of Contents

Prerequisites

Install

Usage

Mock a gRPC server

Unary Method

Client-Stream Method

Server-Stream Method

Bidirectional-Stream Method

Invoke a gRPC method

Unary Method

Client-Stream Method

Server-Stream Method

Bidirectional-Stream Method

Donation

Paypal donation

# Packages

# Functions

# Structs

# Interfaces

# Type aliases