Unit Testing gRPC Services — Complete Guide
gRPC services are harder to unit test than plain HTTP handlers. The generated code is verbose, the transport layer is involved, and developers often reach for integration tests when they should be writing fast, isolated unit tests. This guide shows you the right way to do it in Go, Java, and Python.
Why gRPC Unit Tests Are Different
With REST, you spin up an httptest.Server, fire a request, and assert on the response. With gRPC, the generated code is a thin wrapper over a ClientConn, and the server is typically registered with a grpc.Server. If you naively start a real server in every test, your suite slows down, you introduce port conflicts, and tests start depending on each other.
The solution is to test the service implementation directly — bypass the transport layer entirely — and use in-memory test infrastructure only when you need to verify wire behavior.
Go: Testing the Service Implementation Directly
The generated Go code produces a server interface you implement. That implementation is a plain Go struct. Test it like any other struct.
// user_service.go
type UserService struct {
pb.UnimplementedUserServiceServer
db UserRepository
}
func (s *UserService) GetUser(ctx context.Context, req *pb.GetUserRequest) (*pb.User, error) {
if req.Id == "" {
return nil, status.Error(codes.InvalidArgument, "user id required")
}
user, err := s.db.FindByID(ctx, req.Id)
if err != nil {
return nil, status.Errorf(codes.NotFound, "user %s not found", req.Id)
}
return &pb.User{Id: user.ID, Email: user.Email, Name: user.Name}, nil
}// user_service_test.go
func TestGetUser_ValidID(t *testing.T) {
mockDB := &MockUserRepository{
users: map[string]*User{
"user-1": {ID: "user-1", Email: "alice@example.com", Name: "Alice"},
},
}
svc := &UserService{db: mockDB}
resp, err := svc.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 email %q, want %q", resp.Email, "alice@example.com")
}
}
func TestGetUser_EmptyID(t *testing.T) {
svc := &UserService{db: &MockUserRepository{}}
_, err := svc.GetUser(context.Background(), &pb.GetUserRequest{Id: ""})
if status.Code(err) != codes.InvalidArgument {
t.Errorf("got code %v, want InvalidArgument", status.Code(err))
}
}No server. No port. No network. The test calls the method directly and checks the result. This is what most gRPC unit tests should look like.
Go: Mocking the gRPC Client
When testing code that calls a gRPC service, you need a mock client. The generated Go client is an interface — you can implement it in tests.
// generated interface (simplified)
type UserServiceClient interface {
GetUser(ctx context.Context, in *pb.GetUserRequest, opts ...grpc.CallOption) (*pb.User, error)
ListUsers(ctx context.Context, in *pb.ListUsersRequest, opts ...grpc.CallOption) (UserService_ListUsersClient, error)
}
// mock client
type MockUserServiceClient struct {
GetUserFunc func(ctx context.Context, in *pb.GetUserRequest, opts ...grpc.CallOption) (*pb.User, error)
}
func (m *MockUserServiceClient) GetUser(ctx context.Context, in *pb.GetUserRequest, opts ...grpc.CallOption) (*pb.User, error) {
return m.GetUserFunc(ctx, in, opts...)
}func TestNotificationService_SendWelcomeEmail(t *testing.T) {
mockClient := &MockUserServiceClient{
GetUserFunc: func(ctx context.Context, in *pb.GetUserRequest, opts ...grpc.CallOption) (*pb.User, error) {
return &pb.User{Id: in.Id, Email: "alice@example.com", Name: "Alice"}, nil
},
}
svc := &NotificationService{userClient: mockClient}
err := svc.SendWelcomeEmail(context.Background(), "user-1")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
}For more complex cases, use gomock with the generated mock from mockgen:
mockgen -source=pb/user_grpc.pb.go -destination=mocks/user_mock.go -package=mocksfunc TestWithGomock(t *testing.T) {
ctrl := gomock.NewController(t)
defer ctrl.Finish()
mockClient := mocks.NewMockUserServiceClient(ctrl)
mockClient.EXPECT().
GetUser(gomock.Any(), &pb.GetUserRequest{Id: "user-1"}, gomock.Any()).
Return(&pb.User{Id: "user-1", Email: "alice@example.com"}, nil)
svc := &NotificationService{userClient: mockClient}
err := svc.SendWelcomeEmail(context.Background(), "user-1")
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
}Testing gRPC Interceptors in Go
Interceptors (middleware) are some of the trickiest things to test in gRPC. The unary interceptor signature is:
type UnaryServerInterceptor func(ctx context.Context, req interface{}, info *UnaryServerInfo, handler UnaryHandler) (interface{}, error)You can unit test an interceptor by constructing a fake UnaryHandler and verifying the interceptor's behavior:
func TestAuthInterceptor_ValidToken(t *testing.T) {
interceptor := NewAuthInterceptor([]byte("secret"))
called := false
fakeHandler := func(ctx context.Context, req interface{}) (interface{}, error) {
called = true
return &pb.User{Id: "user-1"}, nil
}
md := metadata.New(map[string]string{
"authorization": "Bearer " + validJWT,
})
ctx := metadata.NewIncomingContext(context.Background(), md)
resp, err := interceptor(ctx, nil, &grpc.UnaryServerInfo{FullMethod: "/UserService/GetUser"}, fakeHandler)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if !called {
t.Error("handler was not called")
}
_ = resp
}
func TestAuthInterceptor_MissingToken(t *testing.T) {
interceptor := NewAuthInterceptor([]byte("secret"))
fakeHandler := func(ctx context.Context, req interface{}) (interface{}, error) {
t.Fatal("handler should not be called")
return nil, nil
}
ctx := metadata.NewIncomingContext(context.Background(), metadata.New(nil))
_, err := interceptor(ctx, nil, &grpc.UnaryServerInfo{}, fakeHandler)
if status.Code(err) != codes.Unauthenticated {
t.Errorf("got code %v, want Unauthenticated", status.Code(err))
}
}Testing Metadata Handling
gRPC metadata is the equivalent of HTTP headers. When you need to verify that your service reads or writes metadata correctly, inject it with metadata.NewIncomingContext:
func TestGetUser_PropagatesRequestID(t *testing.T) {
svc := &UserService{db: &MockUserRepository{
users: map[string]*User{"user-1": {ID: "user-1"}},
}}
md := metadata.Pairs("x-request-id", "req-abc-123")
ctx := metadata.NewIncomingContext(context.Background(), md)
_, err := svc.GetUser(ctx, &pb.GetUserRequest{Id: "user-1"})
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
// If your service uses grpc.SetHeader or grpc.SendHeader, you need a real server
// to inspect response headers. For that, use bufconn (see integration testing guide).
}To verify outgoing metadata from a client, wrap the call with a stats handler or use grpc.Header(&header):
var header metadata.MD
resp, err := client.GetUser(ctx, req, grpc.Header(&header))
if err != nil {
t.Fatal(err)
}
if header.Get("x-trace-id")[0] != "expected-trace" {
t.Errorf("wrong trace id in response header")
}Java: Unit Testing with Mockito and grpc-testing
In Java, grpc-testing provides GrpcCleanupRule and InProcessChannelBuilder for lightweight test infrastructure. But for pure unit tests, mock the StreamObserver directly.
// UserServiceImpl.java
public class UserServiceImpl extends UserServiceGrpc.UserServiceImplBase {
private final UserRepository userRepository;
public UserServiceImpl(UserRepository userRepository) {
this.userRepository = userRepository;
}
@Override
public void getUser(GetUserRequest request, StreamObserver<User> responseObserver) {
if (request.getId().isEmpty()) {
responseObserver.onError(
Status.INVALID_ARGUMENT.withDescription("user id required").asRuntimeException()
);
return;
}
UserEntity entity = userRepository.findById(request.getId())
.orElseThrow(() -> Status.NOT_FOUND.withDescription("not found").asRuntimeException());
responseObserver.onNext(User.newBuilder()
.setId(entity.getId())
.setEmail(entity.getEmail())
.build());
responseObserver.onCompleted();
}
}@ExtendWith(MockitoExtension.class)
class UserServiceImplTest {
@Mock
private UserRepository userRepository;
@Mock
private StreamObserver<User> responseObserver;
private UserServiceImpl service;
@BeforeEach
void setUp() {
service = new UserServiceImpl(userRepository);
}
@Test
void getUser_validId_returnsUser() {
when(userRepository.findById("user-1"))
.thenReturn(Optional.of(new UserEntity("user-1", "alice@example.com")));
service.getUser(
GetUserRequest.newBuilder().setId("user-1").build(),
responseObserver
);
ArgumentCaptor<User> captor = ArgumentCaptor.forClass(User.class);
verify(responseObserver).onNext(captor.capture());
verify(responseObserver).onCompleted();
assertEquals("alice@example.com", captor.getValue().getEmail());
}
@Test
void getUser_emptyId_returnsInvalidArgument() {
service.getUser(GetUserRequest.newBuilder().build(), responseObserver);
ArgumentCaptor<Throwable> captor = ArgumentCaptor.forClass(Throwable.class);
verify(responseObserver).onError(captor.capture());
StatusRuntimeException ex = (StatusRuntimeException) captor.getValue();
assertEquals(Status.Code.INVALID_ARGUMENT, ex.getStatus().getCode());
}
}Python: Unit Testing with grpcio-testing
In Python, the generated servicer is a class you subclass. Test it directly:
import unittest
from unittest.mock import MagicMock, patch
import grpc
from grpc import StatusCode
import user_pb2
import user_pb2_grpc
class UserServicer(user_pb2_grpc.UserServiceServicer):
def __init__(self, user_repo):
self.user_repo = user_repo
def GetUser(self, request, context):
if not request.id:
context.abort(StatusCode.INVALID_ARGUMENT, "user id required")
return user_pb2.User()
user = self.user_repo.find_by_id(request.id)
if user is None:
context.abort(StatusCode.NOT_FOUND, f"user {request.id} not found")
return user_pb2.User()
return user_pb2.User(id=user["id"], email=user["email"])
class TestUserServicer(unittest.TestCase):
def setUp(self):
self.mock_repo = MagicMock()
self.servicer = UserServicer(self.mock_repo)
self.context = MagicMock()
def test_get_user_valid_id(self):
self.mock_repo.find_by_id.return_value = {"id": "user-1", "email": "alice@example.com"}
request = user_pb2.GetUserRequest(id="user-1")
response = self.servicer.GetUser(request, self.context)
self.assertEqual(response.email, "alice@example.com")
self.context.abort.assert_not_called()
def test_get_user_empty_id(self):
request = user_pb2.GetUserRequest(id="")
self.servicer.GetUser(request, self.context)
self.context.abort.assert_called_once_with(
StatusCode.INVALID_ARGUMENT,
"user id required"
)
def test_get_user_not_found(self):
self.mock_repo.find_by_id.return_value = None
request = user_pb2.GetUserRequest(id="nonexistent")
self.servicer.GetUser(request, self.context)
self.context.abort.assert_called_once()
args = self.context.abort.call_args[0]
self.assertEqual(args[0], StatusCode.NOT_FOUND)Note that context.abort() in Python doesn't actually stop execution — the servicer returns normally after calling it. That's why the method returns an empty protobuf after context.abort(). Tests should check that abort was called with the right status code.
Testing Error Codes and Status Details
A common oversight is testing only whether an error occurred, not which gRPC status code was returned. Always assert on the status code:
Go:
if code := status.Code(err); code != codes.NotFound {
t.Errorf("want NotFound, got %v", code)
}Java:
StatusRuntimeException ex = (StatusRuntimeException) captor.getValue();
assertEquals(Status.Code.NOT_FOUND, ex.getStatus().getCode());Python:
self.context.abort.assert_called_with(StatusCode.NOT_FOUND, unittest.mock.ANY)For richer error details (using google.rpc.Status), verify the error details are set correctly before asserting on HTTP/gRPC codes:
st, ok := status.FromError(err)
if !ok {
t.Fatal("not a gRPC status error")
}
details := st.Details()
if len(details) == 0 {
t.Fatal("no error details attached")
}
badRequest, ok := details[0].(*errdetails.BadRequest)
if !ok {
t.Fatalf("expected BadRequest, got %T", details[0])
}
if len(badRequest.FieldViolations) == 0 {
t.Error("expected field violations")
}Structuring Your Test Suite
For a gRPC service, you typically want three layers:
- Unit tests (this guide) — direct method calls, mocked dependencies, test every status code path and business logic branch
- In-process integration tests — real server over
bufconn, testing the full stack including interceptors and metadata propagation (see the integration testing guide) - Contract tests — verify that your proto schema changes don't break consumers (see the Protobuf schema evolution guide)
Keep unit tests in the same package as the service. They run in milliseconds and catch most bugs before anything is deployed.
When to Reach for More
Direct method testing is fast, but it skips the gRPC stack. If you need to verify:
- Interceptor chaining
- Deadline/timeout propagation
- Response trailer handling
- Compression
- Connection-level behavior
...then move to in-process integration tests with bufconn. That keeps tests fast while exercising the real transport layer.
HelpMeTest can run your gRPC tests continuously against deployed services without writing any test code. If you're maintaining a fleet of gRPC services and want regression coverage without the overhead of managing a full test suite, that's where it fits.