gRPC Testing in Python: Unit, Integration, and Mock Strategies
Testing gRPC services in Python requires a different approach than REST APIs. There's no HTTP to intercept, no JSON to assert on. You're working with Protocol Buffers, bidirectional streaming, and generated code. Here's how to test it properly.
Project Setup
Start with a simple service definition:
// user.proto
syntax = "proto3";
package user;
service UserService {
rpc GetUser (GetUserRequest) returns (UserResponse);
rpc ListUsers (ListUsersRequest) returns (stream UserResponse);
rpc CreateUser (CreateUserRequest) returns (UserResponse);
}
message GetUserRequest { string user_id = 1; }
message ListUsersRequest { string department = 1; }
message CreateUserRequest {
string email = 1;
string name = 2;
}
message UserResponse {
string id = 1;
string email = 2;
string name = 3;
}Generate the Python code:
python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. user.protoUnit Testing the Servicer
The servicer is the server-side implementation. Unit test it by calling methods directly — no network needed.
# user_service.py
import user_pb2
import user_pb2_grpc
class UserServicer(user_pb2_grpc.UserServiceServicer):
def __init__(self, user_repo):
self.repo = user_repo
def GetUser(self, request, context):
user = self.repo.find(request.user_id)
if user is None:
context.set_code(grpc.StatusCode.NOT_FOUND)
context.set_details(f"User {request.user_id} not found")
return user_pb2.UserResponse()
return user_pb2.UserResponse(id=user.id, email=user.email, name=user.name)# test_user_servicer.py
import pytest
import grpc
from unittest.mock import MagicMock, patch
import user_pb2
from user_service import UserServicer
class MockContext:
"""Minimal mock for grpc.ServicerContext"""
def __init__(self):
self._code = grpc.StatusCode.OK
self._details = ""
def set_code(self, code):
self._code = code
def set_details(self, details):
self._details = details
def is_active(self):
return True
def test_get_user_returns_user():
mock_repo = MagicMock()
mock_repo.find.return_value = MagicMock(
id='u1', email='alice@example.com', name='Alice'
)
servicer = UserServicer(mock_repo)
request = user_pb2.GetUserRequest(user_id='u1')
context = MockContext()
response = servicer.GetUser(request, context)
assert response.id == 'u1'
assert response.email == 'alice@example.com'
assert context._code == grpc.StatusCode.OK
def test_get_user_sets_not_found_on_miss():
mock_repo = MagicMock()
mock_repo.find.return_value = None
servicer = UserServicer(mock_repo)
request = user_pb2.GetUserRequest(user_id='nonexistent')
context = MockContext()
response = servicer.GetUser(request, context)
assert context._code == grpc.StatusCode.NOT_FOUND
assert 'nonexistent' in context._detailsUnit testing the servicer is fast and dependency-free. The MockContext class is your key tool here.
Testing Streaming RPCs
Server streaming requires the context's is_active() method to control the stream.
# Service method
def ListUsers(self, request, context):
users = self.repo.find_by_department(request.department)
for user in users:
if not context.is_active():
break
yield user_pb2.UserResponse(id=user.id, email=user.email, name=user.name)def test_list_users_streams_all_results():
mock_repo = MagicMock()
mock_repo.find_by_department.return_value = [
MagicMock(id='u1', email='a@example.com', name='Alice'),
MagicMock(id='u2', email='b@example.com', name='Bob'),
]
servicer = UserServicer(mock_repo)
request = user_pb2.ListUsersRequest(department='engineering')
context = MockContext()
responses = list(servicer.ListUsers(request, context))
assert len(responses) == 2
assert responses[0].name == 'Alice'
assert responses[1].name == 'Bob'
def test_list_users_stops_on_client_disconnect():
mock_repo = MagicMock()
mock_repo.find_by_department.return_value = [
MagicMock(id='u1', email='a@example.com', name='Alice'),
MagicMock(id='u2', email='b@example.com', name='Bob'),
]
# Simulate client disconnect after first message
context = MockContext()
call_count = 0
original_is_active = context.is_active
def is_active_once():
nonlocal call_count
call_count += 1
return call_count <= 1
context.is_active = is_active_once
servicer = UserServicer(mock_repo)
request = user_pb2.ListUsersRequest(department='engineering')
responses = list(servicer.ListUsers(request, context))
assert len(responses) == 1 # stopped after firstIntegration Testing with a Real Server
For integration tests, spin up an actual gRPC server in the test.
# conftest.py
import pytest
import grpc
from concurrent import futures
import user_pb2_grpc
from user_service import UserServicer
@pytest.fixture(scope='session')
def grpc_server():
server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
# Use a real in-memory repository for integration tests
repo = InMemoryUserRepository()
repo.save(User(id='u1', email='alice@example.com', name='Alice'))
user_pb2_grpc.add_UserServiceServicer_to_server(
UserServicer(repo), server
)
port = server.add_insecure_port('[::]:0') # random port
server.start()
yield f'localhost:{port}'
server.stop(grace=0)
@pytest.fixture
def user_stub(grpc_server):
channel = grpc.insecure_channel(grpc_server)
return user_pb2_grpc.UserServiceStub(channel)
def test_get_user_integration(user_stub):
response = user_stub.GetUser(user_pb2.GetUserRequest(user_id='u1'))
assert response.email == 'alice@example.com'
def test_get_user_not_found_integration(user_stub):
with pytest.raises(grpc.RpcError) as exc_info:
user_stub.GetUser(user_pb2.GetUserRequest(user_id='nobody'))
assert exc_info.value.code() == grpc.StatusCode.NOT_FOUNDThe add_insecure_port('[::]:0') assigns a random available port, preventing port conflicts in parallel test runs.
Mocking the gRPC Client (Stub)
When testing code that calls a gRPC service, mock the stub.
# order_service.py — calls the user service
class OrderService:
def __init__(self, user_stub):
self.user_stub = user_stub
def create_order(self, user_id, items):
# Verify user exists before creating order
try:
user = self.user_stub.GetUser(
user_pb2.GetUserRequest(user_id=user_id)
)
except grpc.RpcError as e:
if e.code() == grpc.StatusCode.NOT_FOUND:
raise ValueError(f"User {user_id} does not exist")
raise
return Order(user_id=user_id, items=items, user_email=user.email)def test_create_order_validates_user():
mock_user_stub = MagicMock()
# Simulate NOT_FOUND gRPC error
rpc_error = grpc.RpcError()
rpc_error.code = lambda: grpc.StatusCode.NOT_FOUND
mock_user_stub.GetUser.side_effect = rpc_error
order_service = OrderService(user_stub=mock_user_stub)
with pytest.raises(ValueError, match="does not exist"):
order_service.create_order(user_id='nobody', items=['item1'])
def test_create_order_succeeds_for_valid_user():
mock_user_stub = MagicMock()
mock_user_stub.GetUser.return_value = user_pb2.UserResponse(
id='u1', email='alice@example.com', name='Alice'
)
order_service = OrderService(user_stub=mock_user_stub)
order = order_service.create_order(user_id='u1', items=['book', 'pen'])
assert order.user_id == 'u1'
assert order.user_email == 'alice@example.com'
mock_user_stub.GetUser.assert_called_once_with(
user_pb2.GetUserRequest(user_id='u1')
)pytest-grpc: Simplifying Test Setup
The pytest-grpc library reduces boilerplate for service testing.
pip install pytest-grpc# conftest.py
import pytest
import user_pb2_grpc
@pytest.fixture(scope='module')
def grpc_add_to_server():
return user_pb2_grpc.add_UserServiceServicer_to_server
@pytest.fixture(scope='module')
def grpc_servicer():
return UserServicer(InMemoryUserRepository())
# test_with_pytest_grpc.py
def test_get_user(grpc_stub):
# grpc_stub is auto-provided by pytest-grpc
response = grpc_stub.GetUser(user_pb2.GetUserRequest(user_id='u1'))
assert response.name == 'Alice'pytest-grpc handles server setup and teardown, and injects grpc_stub automatically.
Key Testing Patterns
- Unit test the servicer: call methods directly, use
MockContext - Integration test with real server:
add_insecure_port('[::]:0')for random ports - Mock the client stub: use
MagicMock(), simulate errors withside_effect - Test streaming by exhausting the generator:
list(servicer.ListUsers(request, context)) - Test gRPC errors: check
.code()on theRpcError, not the exception message
The generated stub code isn't worth testing — it's Proto-generated. Focus your tests on servicer logic, error handling, and code that calls gRPC services.