Integration Testing gRPC: Real Servers vs Mocks
Unit tests catch logic bugs. Integration tests catch wiring bugs — the kind that only appear when you run a real server, negotiate TLS, and push real bytes over a connection. This guide covers when to use real in-process gRPC servers, when mocks are enough, and how to test TLS, authentication, and channel behavior.
The Spectrum: Mock Stubs to Full Servers
There are four levels of fidelity in gRPC integration testing:
- Direct method calls — no transport, fastest, catches logic bugs only
- In-process server with
bufconn— real gRPC stack, no network, fast, catches interceptor and codec bugs - Loopback TCP server — full network stack, catches connection management bugs, slower
- External service — real deployment, catches infrastructure bugs, slowest and most fragile
For most integration tests, level 2 (bufconn) is the sweet spot. You get the real gRPC stack without port conflicts or network flakiness.
Go: In-Process Servers with bufconn
google.golang.org/grpc/test/bufconn gives you an in-memory network connection that the gRPC server treats as a real TCP connection.
// testserver/server.go
package testserver
import (
"context"
"net"
"testing"
"google.golang.org/grpc"
"google.golang.org/grpc/test/bufconn"
pb "yourproject/gen/pb"
)
const bufSize = 1024 * 1024
func NewServer(t *testing.T, svc pb.UserServiceServer, opts ...grpc.ServerOption) pb.UserServiceClient {
t.Helper()
lis := bufconn.Listen(bufSize)
s := grpc.NewServer(opts...)
pb.RegisterUserServiceServer(s, svc)
go func() {
if err := s.Serve(lis); err != nil {
// server closed is expected on cleanup
}
}()
t.Cleanup(func() {
s.Stop()
lis.Close()
})
conn, err := grpc.DialContext(
context.Background(),
"bufnet",
grpc.WithContextDialer(func(ctx context.Context, _ string) (net.Conn, error) {
return lis.Dial()
}),
grpc.WithInsecure(),
)
if err != nil {
t.Fatalf("failed to dial bufnet: %v", err)
}
t.Cleanup(func() { conn.Close() })
return pb.NewUserServiceClient(conn)
}// user_service_integration_test.go
func TestGetUser_Integration(t *testing.T) {
svc := &UserService{db: &FakeUserRepository{
users: map[string]*User{
"user-1": {ID: "user-1", Email: "alice@example.com"},
},
}}
client := testserver.NewServer(t, svc)
resp, err := client.GetUser(context.Background(), &pb.GetUserRequest{Id: "user-1"})
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if resp.Email != "alice@example.com" {
t.Errorf("got %q, want %q", resp.Email, "alice@example.com")
}
}This tests the full path: serialization, interceptors, metadata propagation, and deserialization — all without touching the network.
Java: GrpcCleanupRule with InProcessChannelBuilder
The grpc-java testing library provides GrpcCleanupRule, which automatically shuts down channels and servers after each test.
@ExtendWith(GrpcExtension.class)
class UserServiceIntegrationTest {
@RegisterExtension
static final GrpcCleanupRule grpcCleanup = new GrpcCleanupRule();
private UserServiceGrpc.UserServiceBlockingStub blockingStub;
@BeforeEach
void setUp() throws IOException {
String serverName = InProcessServerBuilder.generateName();
grpcCleanup.register(
InProcessServerBuilder.forName(serverName)
.directExecutor()
.addService(new UserServiceImpl(new FakeUserRepository()))
.build()
.start()
);
blockingStub = UserServiceGrpc.newBlockingStub(
grpcCleanup.register(
InProcessChannelBuilder.forName(serverName)
.directExecutor()
.build()
)
);
}
@Test
void getUser_returnsCorrectUser() {
User response = blockingStub.getUser(
GetUserRequest.newBuilder().setId("user-1").build()
);
assertEquals("alice@example.com", response.getEmail());
}
@Test
void getUser_notFound_throwsStatusException() {
StatusRuntimeException ex = assertThrows(
StatusRuntimeException.class,
() -> blockingStub.getUser(GetUserRequest.newBuilder().setId("ghost").build())
);
assertEquals(Status.Code.NOT_FOUND, ex.getStatus().getCode());
}
}directExecutor() runs everything on the test thread, which makes tests deterministic and avoids race conditions.
Testing with grpc_cli
grpc_cli is the command-line tool for manually testing gRPC services. It's invaluable for debugging during development and for quick smoke tests in CI.
# List available services (requires server reflection)
grpc_cli ls localhost:50051
# Inspect a service
grpc_cli ls localhost:50051 UserService
# Inspect a method
grpc_cli type localhost:50051 .UserService.GetUser
# Call a unary method
grpc_cli call localhost:50051 UserService.GetUser "id: 'user-1'"
# Call with metadata
grpc_cli call localhost:50051 UserService.GetUser "id: 'user-1'" \
--metadata "authorization: Bearer $TOKEN"
# Call with TLS
grpc_cli call localhost:50051 UserService.GetUser "id: 'user-1'" \
--ssl_target_name_override=myservice.example.com \
--ssl_client_key=client.key \
--ssl_client_cert=client.crt \
--ssl_server_cert=ca.crtTo enable server reflection in Go (required for grpc_cli ls):
import "google.golang.org/grpc/reflection"
s := grpc.NewServer()
pb.RegisterUserServiceServer(s, &UserService{})
reflection.Register(s) // only in non-prodTesting TLS in Integration Tests
For TLS testing, generate self-signed certificates and use them in your test setup. Don't skip TLS testing — TLS mismatches are a common source of production failures.
// Generate test certs (do this once, commit the test certs)
// openssl req -x509 -newkey rsa:4096 -keyout testdata/server.key -out testdata/server.crt \
// -days 3650 -nodes -subj '/CN=localhost'
func NewTLSServer(t *testing.T, svc pb.UserServiceServer) pb.UserServiceClient {
t.Helper()
cert, err := tls.LoadX509KeyPair("testdata/server.crt", "testdata/server.key")
if err != nil {
t.Fatalf("load server cert: %v", err)
}
caCert, err := os.ReadFile("testdata/server.crt")
if err != nil {
t.Fatalf("read CA cert: %v", err)
}
certPool := x509.NewCertPool()
if !certPool.AppendCertsFromPEM(caCert) {
t.Fatal("failed to add CA cert")
}
lis, err := net.Listen("tcp", "127.0.0.1:0")
if err != nil {
t.Fatalf("listen: %v", err)
}
s := grpc.NewServer(grpc.Creds(credentials.NewTLS(&tls.Config{
Certificates: []tls.Certificate{cert},
})))
pb.RegisterUserServiceServer(s, svc)
go s.Serve(lis)
t.Cleanup(func() { s.Stop() })
conn, err := grpc.Dial(
lis.Addr().String(),
grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{
RootCAs: certPool,
ServerName: "localhost",
})),
)
if err != nil {
t.Fatalf("dial: %v", err)
}
t.Cleanup(func() { conn.Close() })
return pb.NewUserServiceClient(conn)
}For mTLS (mutual TLS), also add client certificates to the server's ClientCAs and set ClientAuth: tls.RequireAndVerifyClientCert.
Testing Authentication Interceptors End-to-End
Testing auth with direct method calls only tests the interceptor's internal logic. An integration test verifies that the interceptor is actually wired into the server, that it receives the metadata the client sends, and that it correctly rejects invalid credentials.
func TestAuthInterceptor_Integration(t *testing.T) {
authInterceptor := NewAuthInterceptor([]byte("test-secret"))
client := testserver.NewServer(t, &UserService{db: &FakeUserRepository{
users: map[string]*User{"user-1": {ID: "user-1", Email: "alice@example.com"}},
}}, grpc.UnaryInterceptor(authInterceptor))
t.Run("valid token", func(t *testing.T) {
token := generateJWT("user-1", []byte("test-secret"))
ctx := metadata.AppendToOutgoingContext(
context.Background(),
"authorization", "Bearer "+token,
)
resp, err := client.GetUser(ctx, &pb.GetUserRequest{Id: "user-1"})
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if resp.Email != "alice@example.com" {
t.Errorf("wrong email: %q", resp.Email)
}
})
t.Run("missing token", func(t *testing.T) {
_, err := client.GetUser(context.Background(), &pb.GetUserRequest{Id: "user-1"})
if status.Code(err) != codes.Unauthenticated {
t.Errorf("got %v, want Unauthenticated", status.Code(err))
}
})
t.Run("invalid token", func(t *testing.T) {
ctx := metadata.AppendToOutgoingContext(
context.Background(),
"authorization", "Bearer not-a-real-token",
)
_, err := client.GetUser(ctx, &pb.GetUserRequest{Id: "user-1"})
if status.Code(err) != codes.Unauthenticated {
t.Errorf("got %v, want Unauthenticated", status.Code(err))
}
})
}Channel Management in Tests
A common test bug: reusing a grpc.ClientConn across tests that mutate server state, then getting confused when one test affects another through connection state.
Rules for gRPC channels in tests:
Create one connection per test when tests might affect channel state (e.g., testing retries, keepalive, reconnection):
func TestReconnection(t *testing.T) {
// Each subtest creates its own server and connection
t.Run("reconnects after server restart", func(t *testing.T) {
lis := bufconn.Listen(bufSize)
// ... start server, get client ...
// Stop server, restart it, verify client reconnects
})
}Share one connection across subtests when you're testing concurrent requests on the same channel:
func TestConcurrentRequests(t *testing.T) {
client := testserver.NewServer(t, svc)
// client is shared — tests goroutines through the same connection
var wg sync.WaitGroup
for i := 0; i < 100; i++ {
wg.Add(1)
go func(id string) {
defer wg.Done()
_, err := client.GetUser(context.Background(), &pb.GetUserRequest{Id: id})
// ...
}(fmt.Sprintf("user-%d", i))
}
wg.Wait()
}Always close connections — use t.Cleanup or defer conn.Close(). Leaked connections in long test suites cause port exhaustion and context deadline exceeded errors in unrelated tests.
When Real Servers Beat Mocks
Mocks are faster, but they lie in specific ways. Use a real in-process server when:
- Testing interceptor chains — mocks don't exercise the chain ordering
- Testing codec behavior — custom marshaling only runs with a real server
- Testing deadline propagation — context cancellation behavior requires real gRPC machinery
- Testing streaming — mocking streaming clients/servers is painful and error-prone (see the streaming testing guide)
- Testing connection errors — you need a real connection to test what happens when it drops
Use mocks when:
- Testing code that consumes a gRPC client (not the server implementation)
- You want to control exact return values and error conditions
- The test is a unit test, not an integration test
- You're testing retry/backoff logic at the call site
Debugging Failed Integration Tests
When an integration test fails with a gRPC status error, get the full error details:
if err != nil {
st, ok := status.FromError(err)
if ok {
t.Logf("gRPC status: code=%v, message=%q", st.Code(), st.Message())
for _, d := range st.Details() {
t.Logf(" detail: %T %v", d, d)
}
} else {
t.Logf("non-gRPC error: %v", err)
}
t.Fatal("request failed")
}Enable verbose gRPC logging in tests by setting the environment variable:
GRPC_GO_LOG_VERBOSITY_LEVEL=99 GRPC_GO_LOG_SEVERITY_LEVEL=info go test ./...HelpMeTest can run integration tests against your live gRPC services on every deploy — catching regressions before they reach production without any code changes on your side. Worth looking at if you're maintaining multiple gRPC services across environments.