Integration Testing gRPC: Real Servers vs Mocks

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:

  1. Direct method calls — no transport, fastest, catches logic bugs only
  2. In-process server with bufconn — real gRPC stack, no network, fast, catches interceptor and codec bugs
  3. Loopback TCP server — full network stack, catches connection management bugs, slower
  4. 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.crt

To 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-prod

Testing 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.

Read more

Start now free