Registry / testing / grpcio-testing

grpcio-testing

JSON →
library1.83.1pypypi✓ verified 30d ago

grpcio-testing provides testing utilities for gRPC Python, enabling developers to write unit and integration tests for their gRPC services and clients. It allows for simulating gRPC channels and servers, facilitating isolated testing of gRPC application logic without requiring a full gRPC runtime. The library is currently at version 1.80.0 and follows the release cadence of its parent `grpcio` project, typically with minor updates every six weeks.

pip install grpcio-testing
INSTALL
IMPORT
SIG · GRPCIO-TESTING
G
grpcio-testing
testingpythonv1.83.1
Install
3.7s avg
Import
275ms
Disk
38MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v1.83.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.290s · 40.4MB
glibc
py 3.10–3.910 runs
installs and imports cleanly · install 3.7s · import 0.260s · 39MB
38MB installed
● package 38MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

channel
✓ from grpc_testing import channel
Used to create a test channel for client-side testing.
server_from_dictionary
✓ from grpc_testing import server_from_dictionary
Used to create a test server for service-side testing.
strict_real_time
✓ from grpc_testing import strict_real_time
A Time implementation for tests that operates on real time.
strict_fake_time
✓ from grpc_testing import strict_fake_time
A Time implementation for tests that allows mocking time.
unary_unary_rpc_method_handler
✓ from grpc import unary_unary_rpc_method_handler
✗ from grpcio import unary_unary_rpc_method_handler
Import directly from `grpc` for handlers, not `grpcio`.

This quickstart demonstrates how to use `grpcio-testing` to test a gRPC unary-unary service method. It sets up a mock gRPC server using `server_from_dictionary` and then invokes the service method using `invoke_unary_unary`, asserting on the response and status code. Note that in a real application, `helloworld_pb2` and `helloworld_pb2_grpc` would be generated from your `.proto` files, providing actual message types and method handlers.

import unittest import grpc from grpc_testing import server_from_dictionary, strict_real_time # Assume you have a compiled protobuf service 'helloworld_pb2_grpc.py' # and message types 'helloworld_pb2.py' # For this example, we'll mock them: class MockHelloRequest: def __init__(self, name): self.name = name class MockHelloReply: def __init__(self, message): self.message = message class MockGreeterServicer: def SayHello(self, request, context): if not request.name: context.set_code(grpc.StatusCode.INVALID_ARGUMENT) context.set_details('Name cannot be empty!') return MockHelloReply(message='') return MockHelloReply(message=f'Hello, {request.name}!') # Mock descriptor for server_from_dictionary # In a real scenario, this would come from your generated _pb2_grpc.py def get_method_descriptor(self, method_name): if method_name == '/Greeter/SayHello': # This is a simplified representation; actual descriptor is complex return MockMethodDescriptor('/Greeter/SayHello', MockHelloRequest, MockHelloReply) return None class MockMethodDescriptor: def __init__(self, name, request_type, response_type): self.full_method = name self.input_type = request_type self.output_type = response_type self.has_request_stream = False self.has_response_stream = False class TestGreeterService(unittest.TestCase): def setUp(self): # In a real application, replace with actual generated descriptors # from helloworld_pb2_grpc.DESCRIPTOR or similar. mock_servicer = MockGreeterServicer() service_descriptors = { '/Greeter/SayHello': grpc.unary_unary_rpc_method_handler( mock_servicer.SayHello, request_deserializer=lambda x: MockHelloRequest(''), # Placeholder response_serializer=lambda x: x.message.encode() # Placeholder ) } self.test_server = server_from_dictionary(service_descriptors, strict_real_time()) def test_say_hello_success(self): method_descriptor = self.test_server.get_method_descriptor('/Greeter/SayHello') request = MockHelloRequest(name='World') response, _, code, _ = self.test_server.invoke_unary_unary( method_descriptor, (), # initial metadata request.name.encode(), # Serialized request ).termination() self.assertEqual(code, grpc.StatusCode.OK) # Deserialize response to compare reply = MockHelloReply('') reply.message = response.decode() self.assertEqual(reply.message, 'Hello, World!') def test_say_hello_empty_name(self): method_descriptor = self.test_server.get_method_descriptor('/Greeter/SayHello') request = MockHelloRequest(name='') _, _, code, details = self.test_server.invoke_unary_unary( method_descriptor, (), request.name.encode(), ).termination() self.assertEqual(code, grpc.StatusCode.INVALID_ARGUMENT) self.assertEqual(details, 'Name cannot be empty!') if __name__ == '__main__': unittest.main()
Debug
Known issues
gotchaOfficial documentation and clear, simple examples for `grpcio-testing` are historically sparse, making the learning curve steeper for new users. Users often resort to examining the `grpcio` project's internal tests for usage patterns.
fix
Refer to the `grpcio` GitHub repository's `src/python/grpcio_tests` directory for examples and patterns. Engaging with the gRPC community forums can also provide guidance. Consider contributing examples if you develop robust testing patterns.
affects: All versions
breakingWhen testing asynchronous RPCs, `grpcio-testing` might not return the correct status code and details, which can lead to misrepresentation of error handling in tests.
fix
For critical asynchronous RPC error path testing, consider using actual gRPC client/server setups instead of `grpcio-testing`'s mocking capabilities, or implement custom assertions to work around the discrepancy. Track `grpcio` issues for resolution.
affects: Potentially all versions, specifically noted in issue #40597 (Sept 2025).
gotchaTesting gRPC server interceptors directly with `grpcio-testing` is not straightforward and might not be fully supported, limiting the ability to comprehensively test interceptor logic at the gRPC layer.
fix
Consider testing interceptors in isolation as plain Python functions or, for integration-level testing, use a full gRPC server setup rather than `grpcio-testing`. Some developers resort to using decorators as an alternative to interceptors for unit testing purposes.
affects: All versions, noted in issue #28214 (Nov 2021).
breakingThere have been reports of significant test flakiness and connection issues when `grpcio` (a core dependency) is upgraded to versions like 1.66.x, potentially related to gRPC's fork support. This can indirectly affect `grpcio-testing` users.
fix
If experiencing test flakiness or connection issues, try pinning your `grpcio` dependency to a version prior to 1.66.0 (e.g., `<1.66.0`). Monitor `grpcio`'s GitHub issues for resolutions and updates regarding fork support and stability.
affects: grpcio versions >= 1.66.0 (as of Sept 2024).
gotchaVersion conflicts between `grpcio` and `protobuf` can occur, especially if `grpcio` is installed without `grpcio-tools`, or if different versions of `protobuf` are introduced by other dependencies. This can lead to runtime errors due to incompatible generated code.
fix
Always install `grpcio` and `grpcio-tools` together, ideally from the same version range, to ensure `protobuf` compatibility. Use a virtual environment to isolate dependencies. If conflicts arise, explicitly pin `protobuf` to a version compatible with your `grpcio` installation.
affects: Potentially all versions; noted with `grpcio==1.12.0` (May 2018) and `grpcio==1.72.0` (April 2025).
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'grpc'
The `grpcio` package, which provides the core gRPC Python functionality, is not installed in the active Python environment or is not discoverable in the Python path. `grpcio-testing` depends on `grpcio`.
fix
Ensure `grpcio` is installed using pip: `pip install grpcio`
ModuleNotFoundError: No module named 'grpc_tools'
The `grpcio-tools` package, which provides utilities for compiling .proto files into Python code, is not installed. This package is often needed to generate the service and message definitions that `grpcio-testing` uses.
fix
Install `grpcio-tools` using pip: `pip install grpcio-tools`
AttributeError: module 'grpc' has no attribute '_channel'
This error typically occurs when the `grpcio` package is partially or incorrectly installed, leading to missing internal modules or corrupted C extensions, even if the top-level `grpc` module can be imported.
fix
Reinstall `grpcio` and its dependencies, potentially in a clean virtual environment, ensuring a complete build: `pip uninstall grpcio grpcio-tools protobuf` (if present) followed by `pip install --no-cache-dir --upgrade pip setuptools grpcio grpcio-tools`
ERROR: Could not find a version that satisfies the requirement grpcio<2,>=1.29.0 (from apache-beam[gcp])
This installation error indicates that `pip` could not find a compatible `grpcio` wheel for your specific Python version, operating system, or architecture, or there's a conflict with other installed packages requiring different versions.
fix
Ensure your `pip` and `setuptools` are up-to-date (`pip install --upgrade pip setuptools`). If the issue persists, try installing a specific `grpcio` version known to be compatible with your environment, or consider using a different Python version, as pre-built wheels might not be available for all combinations. For specific scenarios like `apache-beam`, consult their compatibility matrix.
Upgrade
Version history
1.83.1latest on PyPI · released Aug 28, 2026
Audit
Dependencies
grpciorequiredRuntime dependency for gRPC functionality.
grpcio-toolsoptionalNeeded for compiling .proto files into Python code.
Agent activity
15 hits · last 30 days
node
12
Amazon
1
Resources
grpcio-testing — pip install grpcio-testing · libregistry