Testing Go gRPC Server Using an in-memory Buffer with `bufconn`
Jan 17, 2020
3 minute read

It can be cumbersome to setup a testing environment targeting a live server to implement full API testing against your gRPC server. Even spinning up a server from your test file can lead to unintended consequences that require you to allocate a TCP port (parallel runs, multiple runs under same CI server).

bufconn is a package which provides a Listener object that implements net.Conn. We can substitute this listener in a gRPC server - allowing us to spin up a server that acts as a full-fledged server that can be used for testing that talks over an in-memory buffer instead of a real port.


  • Spin up a gRPC server using an in-memory buffer
  • Use the server in a standard testing.Test test function


Same as my other post, I created a simple gRPC service that implements Ping and StreamPring. Calling Ping replies with (you guessed it!) a pong message. StreamPing is similar, but you can specify how many times it pong’s back.

syntax = "proto3";

package ping;

option go_package = "protos";

service Pinger {
    rpc Ping(PingRequest) returns (PingResponse) {}
    rpc PingStream (PingRequest) returns (stream PingResponse) {}

message PingRequest {
    int32 count = 1;

message PingResponse {
    bytes payload = 1;

Using bufconn

To easily spin up a server and a client that talk over a bufconn buffer, I created a function that is called by the test file:

func server(ctx context.Context) (pb.PingerClient, func()) {
	buffer := 1024 * 1024
	listener := bufconn.Listen(buffer)

	s := grpc.NewServer()
	pb.RegisterPingerServer(s, &Pinger{})
	go func() {
		if err := s.Serve(listener); err != nil {

	conn, _ := grpc.DialContext(ctx, "", grpc.WithContextDialer(func(context.Context, string) (net.Conn, error) {
		return listener.Dial()
	}), grpc.WithInsecure())

	closer := func() {

	client := pb.NewPingerClient(conn)

	return client, closer

Important thing to note here are, this function:

  • Spins up gRPC server using the bufconn buffer
  • Creates a client that talks over the buffer using gRPC.WithContextDialer
  • Returns function to terminate the listener and the server

Using the bufconn client

With the above function, the rest are easy:

ctx := context.Background()
assert := assert.New(t)

client, closer := server(ctx)
defer closer()

out, err := client.Ping(ctx, tc.in)

if tc.expected.err == nil {
    assert.Equal(tc.expected.out, out)
} else {
    assert.Equal(tc.expected.err, err)

That is the meat of my test. It uses the server function, after making sure the closer is defered, it uses the client to make a request. The response is asserted against expectation. This all happens against a gRPC server, except it uses bufconn instead of a TCP socket.

Source code for the full setup is available here.


bufconn allows you to spin up a gRPC server that talk over an in-memory buffer. Tests are fast and reliable, and allows you to easily setup integration style tests that uses a full server.

comments powered by Disqus