Testing gRPC Services

Analogy categoryAnalogies

Unit Testing gRPC Service Implementations

The cleanest way to unit test a gRPC service is to test the handler logic directly, calling the generated server method with a plain request object and a context, bypassing the network stack entirely. In Go this means instantiating your service struct and calling its method like any other Go function, asserting on the returned message and error; in Node.js it means calling the handler function with a mock call object exposing request and a callback spy. This approach is fast and deterministic because it avoids sockets, serialization, and TLS handshakes, isolating exactly the business logic you changed.

🏏

Cricket analogy: Testing the handler directly without a network call is like a batter facing throwdowns from a coach in the nets rather than a full live match, isolating technique from all the variables of an actual game.

Integration Testing with an In-Process or Local Server

Once handler logic is verified, integration tests should exercise the real gRPC wire protocol by spinning up an actual server, often on an in-memory or bufconn-style listener in Go, or a real localhost port in Node, and connecting a generated client to it. This catches classes of bugs unit tests miss entirely: incorrect proto field tags causing silent data loss, interceptor ordering bugs, metadata propagation issues, and status code mapping errors that only appear once messages are actually serialized and deserialized across the wire. Go's google.golang.org/grpc/test/bufconn package is the standard tool for this because it avoids real network ports while still exercising the full client-server RPC path.

🏏

Cricket analogy: Running the full wire protocol in a test is like a day-night pink-ball practice match under real match conditions instead of net practice, surfacing issues like ball behavior under lights that nets never would.

func TestGetOrder_Integration(t *testing.T) {
	lis := bufconn.Listen(1024 * 1024)
	srv := grpc.NewServer()
	pb.RegisterOrderServiceServer(srv, &orderServer{})
	go srv.Serve(lis)
	defer srv.Stop()

	conn, err := grpc.DialContext(context.Background(), "bufnet",
		grpc.WithContextDialer(func(ctx context.Context, s string) (net.Conn, error) {
			return lis.Dial()
		}),
		grpc.WithTransportCredentials(insecure.NewCredentials()))
	require.NoError(t, err)
	defer conn.Close()

	client := pb.NewOrderServiceClient(conn)
	resp, err := client.GetOrder(context.Background(), &pb.OrderRequest{Id: "o-42"})
	require.NoError(t, err)
	require.Equal(t, "SHIPPED", resp.Status)
}

Manual and Ad-Hoc Testing with grpcurl

For manual exploration and debugging, grpcurl is the gRPC equivalent of curl for REST: it can invoke any RPC from the command line, either against a server with the reflection service enabled or by pointing directly at .proto files with the -proto and -import-path flags. This is invaluable during development for hitting an endpoint without writing any client code, and it's often wired into CI smoke tests or health-check scripts that verify a deployed service responds correctly after a rollout, without needing a full generated client in the CI pipeline's own language.

🏏

Cricket analogy: Using grpcurl for ad-hoc calls is like a coach using a simple radar gun to check one bowler's pace during a casual net session, quick, targeted, no full match setup needed.

grpcurl requires either server reflection enabled (via google.golang.org/grpc/reflection or the equivalent Node package) or explicit .proto files passed with -proto/-import-path. Enabling reflection in non-production environments makes exploratory testing and debugging significantly faster, but many teams disable it in production for security reasons since it exposes the full service and message schema to anyone who can reach the port.

Unit test handler logic directly by calling the generated method with a crafted request, bypassing the network entirely.
Integration tests should exercise the real wire protocol, catching serialization, interceptor, and status-mapping bugs.
Go's bufconn package lets integration tests run a real client-server RPC path without opening a real network port.
grpcurl acts as curl for gRPC, invoking RPCs manually via reflection or explicit .proto files.
Server reflection speeds up manual testing but is often disabled in production for security reasons.
CI smoke tests can use grpcurl to verify a deployed service responds correctly without a full generated client.
Mocking generated clients (interfaces in Go, or stub objects in Node) lets calling code be tested without a live server.