{"id":8530,"library":"pytest-grpc","title":"pytest-grpc plugin","description":"pytest-grpc is a pytest plugin for testing gRPC services. It provides fixtures to start and stop gRPC servers and clients, allowing interaction with gRPC services during tests. The current stable version is 0.8.0, with releases occurring as new features are added or significant bugs are fixed, often following `pytest` or `grpcio` releases.","status":"active","version":"0.8.0","language":"en","source_language":"en","source_url":"https://github.com/pytest-dev/pytest-grpc","tags":["pytest","grpc","testing","plugin"],"install":[{"cmd":"pip install pytest-grpc","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core testing framework, pytest-grpc is a plugin for it.","package":"pytest","optional":false},{"reason":"Required for gRPC communication, server, and client functionality.","package":"grpcio","optional":false}],"imports":[{"note":"Fixture for a gRPC channel connected to the test server.","symbol":"grpc_channel","correct":"def test_example(grpc_channel): ..."},{"note":"Fixture for a gRPC stub connected to the test server. Requires `pytest_grpc_servicer_create` hook in conftest.py.","symbol":"grpc_stub","correct":"def test_example(grpc_stub): ..."},{"note":"Factory fixture to explicitly create and manage gRPC servers within tests.","symbol":"grpc_server_factory","correct":"def test_example(grpc_server_factory): ..."},{"note":"Hook to register the servicer's add_to_server function.","symbol":"grpc_add_to_server","correct":"import your_service_pb2_grpc\n@pytest.fixture(scope='session')\ndef grpc_add_to_server():\n    return your_service_pb2_grpc.add_YourServiceServicer_to_server"},{"note":"Hook to provide the gRPC servicer instance.","symbol":"grpc_servicer","correct":"import pytest\nclass MyServicer(YourServiceServicer):\n    ...\n@pytest.fixture(scope='session')\ndef grpc_servicer():\n    return MyServicer()"}],"quickstart":{"code":"# conftest.py\nimport pytest\nimport grpc\n\n# Assuming you have compiled your_service.proto into your_service_pb2.py and your_service_pb2_grpc.py\n# e.g., using 'python -m grpc_tools.protoc -I. --python_out=. --grpc_python_out=. your_service.proto'\nimport your_service_pb2_grpc\nfrom your_service_pb2 import HelloRequest, HelloReply\n\n# Define your gRPC Servicer implementation\nclass MyTestServicer(your_service_pb2_grpc.GreeterServicer):\n    def SayHello(self, request, context):\n        return HelloReply(message=f\"Hello, {request.name} from test!\")\n\n# Provide the servicer instance\n@pytest.fixture(scope='session')\ndef grpc_servicer():\n    return MyTestServicer()\n\n# Provide the 'add_to_server' function from your generated _grpc module\n@pytest.fixture(scope='session')\ndef grpc_add_to_server():\n    return your_service_pb2_grpc.add_GreeterServicer_to_server\n\n# test_service.py\nimport your_service_pb2\n\ndef test_say_hello(grpc_stub):\n    # grpc_stub is an automatically created stub for your service\n    request = your_service_pb2.HelloRequest(name=\"World\")\n    response = grpc_stub.SayHello(request)\n    assert response.message == \"Hello, World from test!\"\n\ndef test_say_hello_with_channel(grpc_channel):\n    # You can also create a stub manually if needed\n    stub = your_service_pb2_grpc.GreeterStub(grpc_channel)\n    request = your_service_pb2.HelloRequest(name=\"ChannelUser\")\n    response = stub.SayHello(request)\n    assert response.message == \"Hello, ChannelUser from test!\"\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"breaking","affected_versions":"< 0.6.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"AttributeError: 'module' object has no attribute 'YourMethod' (or similar method missing)"},{"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.","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.","error":"grpc._channel._MultiThreadedRendezvous: <_Rendezvous of RPC that terminated with: status = StatusCode.UNAVAILABLE details = \"failed to connect to all addresses\" >"},{"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.","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.","error":"pytest.FixtureLookupError: Unknown fixture 'grpc_stub'"}]}