pytest-grpc plugin

Common errors

• AttributeError: 'module' object has no attribute 'YourMethod' (or similar method missing)

  cause The gRPC stub or servicer defined in your `conftest.py` does not match the service definition expected by your test code, or your `.proto` files were not correctly compiled.
  fix Verify that your `grpc_servicer` fixture returns an instance of the correct servicer implementation and that `grpc_add_to_server` points to the correct `add_Servicer_to_server` function from your generated `_grpc.py` file. Regenerate your `.proto` files if necessary.

• grpc._channel._MultiThreadedRendezvous: <_Rendezvous of RPC that terminated with: status = StatusCode.UNAVAILABLE details = "failed to connect to all addresses" >

  cause The gRPC test server failed to start or the client could not connect to it. This can happen if the `pytest_grpc_servicer_create` hook (or `grpc_servicer` and `grpc_add_to_server`) is missing or misconfigured, preventing the server from being set up.
  fix Ensure your `conftest.py` correctly defines `grpc_servicer` and `grpc_add_to_server` fixtures. Check for any errors during pytest startup that might indicate the server failing to bind to a port or an issue with the servicer instantiation.

• pytest.FixtureLookupError: Unknown fixture 'grpc_stub'

  cause The `pytest-grpc` plugin is not installed or not active, or pytest cannot find your `conftest.py` where the plugin-required hooks are defined.
  fix Make sure `pytest-grpc` is installed (`pip install pytest-grpc`). Ensure your `conftest.py` is in the root of your test suite or an appropriate parent directory recognized by pytest, and that it contains the necessary `grpc_servicer` and `grpc_add_to_server` fixtures.

Warnings

• gotcha The `grpc_stub` fixture requires `pytest_grpc_servicer_create` (or directly `grpc_servicer` and `grpc_add_to_server`) to be defined in your `conftest.py`. Without these hooks, `pytest-grpc` cannot know which servicer to instantiate and register to the test server, leading to errors when trying to use `grpc_stub`.
  Fix: Define `grpc_servicer` and `grpc_add_to_server` fixtures in your `conftest.py` as shown in the quickstart example, providing your gRPC servicer implementation and its `add_to_server` function.
• breaking Older versions (pre-0.6.0) might have used a `grpc_server` fixture which has been refactored. The recommended way to explicitly control server creation is now `grpc_server_factory`.
  Fix: Migrate tests using `grpc_server` to use `grpc_server_factory` if you need fine-grained control over server creation, or rely on the `grpc_channel`/`grpc_stub` fixtures which implicitly manage a server for you.
• gotcha When developing, ensure your `.proto` files are correctly compiled into Python modules (`_pb2.py` and `_pb2_grpc.py`) and are accessible on your Python path. Missing or outdated generated files can lead to import errors or `AttributeError`s.
  Fix: Run `python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. your_service.proto` (adjust paths as needed) to generate files. Ensure the directory containing these files is in your `PYTHONPATH` or is imported correctly.

Install

• pip install pytest-grpc Install stable version

Imports

• grpc_channel

  def test_example(grpc_channel): ...

  Fixture for a gRPC channel connected to the test server.
• grpc_stub

  def test_example(grpc_stub): ...

  Fixture for a gRPC stub connected to the test server. Requires `pytest_grpc_servicer_create` hook in conftest.py.
• grpc_server_factory

  def test_example(grpc_server_factory): ...

  Factory fixture to explicitly create and manage gRPC servers within tests.
• grpc_add_to_server

  import your_service_pb2_grpc
  @pytest.fixture(scope='session')
  def grpc_add_to_server():
      return your_service_pb2_grpc.add_YourServiceServicer_to_server

  Hook to register the servicer's add_to_server function.
• grpc_servicer

  import pytest
  class MyServicer(YourServiceServicer):
      ...
  @pytest.fixture(scope='session')
  def grpc_servicer():
      return MyServicer()

  Hook to provide the gRPC servicer instance.

Quickstart

This quickstart demonstrates how to set up `pytest-grpc` using `conftest.py` to provide a test servicer and its `add_to_server` function. It then shows how to write a basic test using the `grpc_stub` fixture, which automatically handles server setup and client stub creation, or using `grpc_channel` to create a stub manually. This setup assumes you have generated Python gRPC code from your `.proto` definitions.

# conftest.py
import pytest
import grpc

# Assuming you have compiled your_service.proto into your_service_pb2.py and your_service_pb2_grpc.py
# e.g., using 'python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. your_service.proto'
import your_service_pb2_grpc
from your_service_pb2 import HelloRequest, HelloReply

# Define your gRPC Servicer implementation
class MyTestServicer(your_service_pb2_grpc.GreeterServicer):
    def SayHello(self, request, context):
        return HelloReply(message=f"Hello, {request.name} from test!")

# Provide the servicer instance
@pytest.fixture(scope='session')
def grpc_servicer():
    return MyTestServicer()

# Provide the 'add_to_server' function from your generated _grpc module
@pytest.fixture(scope='session')
def grpc_add_to_server():
    return your_service_pb2_grpc.add_GreeterServicer_to_server

# test_service.py
import your_service_pb2

def test_say_hello(grpc_stub):
    # grpc_stub is an automatically created stub for your service
    request = your_service_pb2.HelloRequest(name="World")
    response = grpc_stub.SayHello(request)
    assert response.message == "Hello, World from test!"

def test_say_hello_with_channel(grpc_channel):
    # You can also create a stub manually if needed
    stub = your_service_pb2_grpc.GreeterStub(grpc_channel)
    request = your_service_pb2.HelloRequest(name="ChannelUser")
    response = stub.SayHello(request)
    assert response.message == "Hello, ChannelUser from test!"