grpctest

README

grpctest

grpctest is a package providing utilities for testing gRPC servers. Specifically it formalises a pattern of writing integration style tests by exercising the full gRPC stack.

Prerequisites

You will need the following things properly installed on your computer.

• Go: any one of the three latest major releases

Installation

With Go module support (Go 1.11+), simply add the following import

import "github.com/crumbandbase/grpctest"

to your code, and then go [build|run|test] will automatically fetch the necessary dependencies.

Otherwise, to install the grpctest package, run the following command:

$ go get -u github.com/crumbandbase/grpctest

Usage

To use this package start by implementing the gRPC server stubs as normal. This will form the foundation of the tests. In this example a type implementing the EchoServer interface has been created to echo back the request to the caller.

package server

import (
	"context"

	echopb "github.com/crumbandbase/grpctest/echo/proto"
)

type EchoServer struct {
	echopb.UnimplementedEchoServer
}

func (s *EchoServer) Echo(ctx context.Context, in *echopb.EchoRequest) (*echopb.EchoResponse, error) {
	return &echopb.EchoResponse{Message: in.Message}, nil
}

To the test the server implementation create a gRPC server using the grpctest.NewServer function. This instantiates a wrapper around a regular gRPC server using an in-memory buffer to send and receive data. The wrapper also exposes methods to create gRPC client connections across the buffer. These may be used when instantiating new gRPC clients.

The example below demonstrates this within the context of a test.

package server_test

import (
	"context"
	"testing"

	"github.com/crumbandbase/grpctest"
	echopb "github.com/crumbandbase/grpctest/echo/proto"
	"github.com/crumbandbase/grpctest/echo/server"
)

func setupRecoveryServer(t *testing.T) (grpctest.Closer, echopb.EchoClient) {
	s := grpctest.NewServer()

	conn, err := s.ClientConn()
	if err != nil {
		t.Fatal(err)
	}

	echopb.RegisterEchoServer(s, &server.EchoServer{})
	s.Serve()

	return s.Close, echopb.NewEchoClient(conn)
}

func TestEcho(t *testing.T) {
	t.Run("returns the same message sent to the server", func(t *testing.T) {
		closer, client := setupRecoveryServer(t)
		defer closer()

		message := "Hello, world"
		resp, err := client.Echo(context.Background(), &echopb.EchoRequest{Message: message})
		if err != nil {
			t.Errorf("expected: nil, got: %v", err)
		}

		if resp.Message != message {
			t.Errorf("expected: %s, got: %s", message, resp.Message)
		}
	})
}

License

This project is licensed under the MIT License.

Documentation

Index

• type Closer
• type Server
  • func NewServer(opts ...grpc.ServerOption) *Server
  • func NewTLSServer(opts ...grpc.ServerOption) *Server
  • func (s *Server) Certificate() *x509.Certificate
  • func (s *Server) ClientConn(opts ...grpc.DialOption) (*grpc.ClientConn, error)
  • func (s *Server) ClientConnContext(ctx context.Context, opts ...grpc.DialOption) (*grpc.ClientConn, error)
  • func (s *Server) Close()
  • func (s *Server) Serve()

Types

type Closer

type Closer func()

Closer is a convenience type to be used in test suites.

type Server

type Server struct {
	*grpc.Server

	Listener *bufconn.Listener
	TLS      *tls.Config
	// contains filtered or unexported fields
}

Server is a gRPC server listening on a buffered stream, for use in end-to-end gRPC tests.

func NewServer

func NewServer(opts ...grpc.ServerOption) *Server

NewServer returns a new insecure server. The caller should start the server by calling Serve on the returned type, and call Close when finished, to shut it down.

func NewTLSServer

func NewTLSServer(opts ...grpc.ServerOption) *Server

NewTLSServer returns a new secure server. The caller should start the server by calling Serve on the returned type, and call Close when finished, to shut it down.

func (*Server) Certificate

func (s *Server) Certificate() *x509.Certificate

Certificate returns the certificate used by the server, or nil if the server doesn't use TLS.

func (*Server) ClientConn

func (s *Server) ClientConn(opts ...grpc.DialOption) (*grpc.ClientConn, error)

ClientConn returns a gRPC client connection configured for making requests to the server. It is configured to trust the server's TLS test certificate, if present, and will close its idle connections on Close.

func (*Server) ClientConnContext

func (s *Server) ClientConnContext(ctx context.Context, opts ...grpc.DialOption) (*grpc.ClientConn, error)

ClientConnContext returns a gRPC client connection configured for making requests to the server. It is configured to trust the server's TLS test certificate, if present, and will close its idle connections on Close.

func (*Server) Close

func (s *Server) Close()

Close shuts down the server and blocks until all outstanding requests on this server have completed.

func (*Server) Serve

func (s *Server) Serve()

Start starts the server.