gRPC Testing in Python: Unit, Integration, and Mock Strategies

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

Unit 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._details

Unit 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 first

Integration 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_FOUND

The 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 with side_effect
  • Test streaming by exhausting the generator: list(servicer.ListUsers(request, context))
  • Test gRPC errors: check .code() on the RpcError, 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.

Read more

Start now free