Module Contents¶

Objects for use in testing gRPC Python-using application code.

classgrpc_testing.Channel[source]¶

A grpc.Channel double with which to test a system that invokes RPCs.

abstracttake_stream_stream(method_descriptor)[source]¶

Draws an RPC currently being made by the system under test.

If the given descriptor does not identify any RPC currently being madeby the system under test, this method blocks until the system undertest invokes such an RPC.

Parameters:

method_descriptor – A descriptor.MethodDescriptor describing astream-stream RPC method.

Returns:

A (invocation_metadata, stream_stream_channel_rpc) tuple of the RPC’s

invocation metadata and a StreamStreamChannelRpc with which to“play server” for the RPC.

abstracttake_stream_unary(method_descriptor)[source]¶

Draws an RPC currently being made by the system under test.

If the given descriptor does not identify any RPC currently being madeby the system under test, this method blocks until the system undertest invokes such an RPC.

Parameters:

method_descriptor – A descriptor.MethodDescriptor describing astream-unary RPC method.

Returns:

A (invocation_metadata, stream_unary_channel_rpc) tuple of the RPC’s

invocation metadata and a StreamUnaryChannelRpc with which to “playserver” for the RPC.

abstracttake_unary_stream(method_descriptor)[source]¶

Draws an RPC currently being made by the system under test.

If the given descriptor does not identify any RPC currently being madeby the system under test, this method blocks until the system undertest invokes such an RPC.

Parameters:

method_descriptor – A descriptor.MethodDescriptor describing aunary-stream RPC method.

Returns:

A (invocation_metadata, request, unary_stream_channel_rpc) tuple of

the RPC’s invocation metadata, its request, and aUnaryStreamChannelRpc with which to “play server” for the RPC.

abstracttake_unary_unary(method_descriptor)[source]¶

Draws an RPC currently being made by the system under test.

If the given descriptor does not identify any RPC currently being madeby the system under test, this method blocks until the system undertest invokes such an RPC.

Parameters:

method_descriptor – A descriptor.MethodDescriptor describing aunary-unary RPC method.

Returns:

A (invocation_metadata, request, unary_unary_channel_rpc) tuple of

the RPC’s invocation metadata, its request, and aUnaryUnaryChannelRpc with which to “play server” for the RPC.

classgrpc_testing.Server[source]¶

A server with which to test a system that services RPCs.

abstractinvoke_stream_stream(method_descriptor,invocation_metadata,timeout)[source]¶

Invokes an RPC to be serviced by the system under test.

Parameters:

• method_descriptor – A descriptor.MethodDescriptor describing a stream-streamRPC method.

• invocation_metadata – The RPC’s invocation metadata.

• timeout – A duration of time in seconds for the RPC or None toindicate that the RPC has no time limit.

Returns:

A StreamStreamServerRpc with which to “play client” for the RPC.

abstractinvoke_stream_unary(method_descriptor,invocation_metadata,timeout)[source]¶

Invokes an RPC to be serviced by the system under test.

Parameters:

• method_descriptor – A descriptor.MethodDescriptor describing a stream-unaryRPC method.

• invocation_metadata – The RPC’s invocation metadata.

• timeout – A duration of time in seconds for the RPC or None toindicate that the RPC has no time limit.

Returns:

A StreamUnaryServerRpc with which to “play client” for the RPC.

abstractinvoke_unary_stream(method_descriptor,invocation_metadata,request,timeout)[source]¶

Invokes an RPC to be serviced by the system under test.

Parameters:

• method_descriptor – A descriptor.MethodDescriptor describing a unary-streamRPC method.

• invocation_metadata – The RPC’s invocation metadata.

• request – The RPC’s request.

• timeout – A duration of time in seconds for the RPC or None toindicate that the RPC has no time limit.

Returns:

A UnaryStreamServerRpc with which to “play client” for the RPC.

abstractinvoke_unary_unary(method_descriptor,invocation_metadata,request,timeout)[source]¶

Invokes an RPC to be serviced by the system under test.

Parameters:

• method_descriptor – A descriptor.MethodDescriptor describing a unary-unaryRPC method.

• invocation_metadata – The RPC’s invocation metadata.

• request – The RPC’s request.

• timeout – A duration of time in seconds for the RPC or None toindicate that the RPC has no time limit.

Returns:

A UnaryUnaryServerRpc with which to “play client” for the RPC.

classgrpc_testing.StreamStreamChannelRpc[source]¶

Fixture for a stream-stream RPC invoked by a system under test.

Enables users to “play server” for the RPC.

abstractcancelled()[source]¶

Blocks until the system under test has cancelled the RPC.

abstractrequests_closed()[source]¶

Blocks until the system under test has closed the request stream.

abstractsend_initial_metadata(initial_metadata)[source]¶

Sends the RPC’s initial metadata to the system under test.

Parameters:

initial_metadata – The RPC’s initial metadata to be “sent” to thesystem under test.

abstractsend_response(response)[source]¶

Sends a response to the system under test.

Parameters:

response – A response messages to be “sent” to the system under test.

abstracttake_request()[source]¶

Draws one of the requests added to the RPC by the system under test.

This method blocks until the system under test has added to the RPCthe request to be returned.

Successive calls to this method return requests in the same order inwhich the system under test added them to the RPC.

Returns:

A request message added to the RPC by the system under test.

abstractterminate(trailing_metadata,code,details)[source]¶

Terminates the RPC.

Parameters:

• trailing_metadata – The RPC’s trailing metadata.

• code – The RPC’s status code.

• details – The RPC’s status details.

classgrpc_testing.StreamStreamServerRpc[source]¶

Fixture for a stream-stream RPC serviced by a system under test.

Enables users to “play client” for the RPC.

abstractcancel()[source]¶

Cancels the RPC.

abstractinitial_metadata()[source]¶

Accesses the initial metadata emitted by the system under test.

This method blocks until the system under test has added initialmetadata to the RPC (or has provided one or more response messages orhas terminated the RPC, either of which will cause gRPC Python tosynthesize initial metadata for the RPC).

Returns:

The initial metadata for the RPC.

abstractrequests_closed()[source]¶

Indicates the end of the RPC’s request stream.

abstractsend_request(request)[source]¶

Sends a request to the system under test.

Parameters:

request – A request message for the RPC to be “sent” to the systemunder test.

abstracttake_response()[source]¶

Draws one of the responses added to the RPC by the system under test.

Successive calls to this method return responses in the same order inwhich the system under test added them to the RPC.

Returns:

A response message added to the RPC by the system under test.

abstracttermination()[source]¶

Blocks until the system under test has terminated the RPC.

Returns:

A (trailing_metadata, code, details) sequence with the RPC’s trailing

metadata, code, and details.

classgrpc_testing.StreamUnaryChannelRpc[source]¶

Fixture for a stream-unary RPC invoked by a system under test.

Enables users to “play server” for the RPC.

abstractcancelled()[source]¶

Blocks until the system under test has cancelled the RPC.

abstractrequests_closed()[source]¶

Blocks until the system under test has closed the request stream.

abstractsend_initial_metadata(initial_metadata)[source]¶

Sends the RPC’s initial metadata to the system under test.

Parameters:

initial_metadata – The RPC’s initial metadata to be “sent” tothe system under test.

abstracttake_request()[source]¶

Draws one of the requests added to the RPC by the system under test.

This method blocks until the system under test has added to the RPCthe request to be returned.

Successive calls to this method return requests in the same order inwhich the system under test added them to the RPC.

Returns:

A request message added to the RPC by the system under test.

abstractterminate(response,trailing_metadata,code,details)[source]¶

Terminates the RPC.

Parameters:

• response – The response for the RPC.

• trailing_metadata – The RPC’s trailing metadata.

• code – The RPC’s status code.

• details – The RPC’s status details.

classgrpc_testing.StreamUnaryServerRpc[source]¶

Fixture for a stream-unary RPC serviced by a system under test.

Enables users to “play client” for the RPC.

abstractcancel()[source]¶

Cancels the RPC.

abstractinitial_metadata()[source]¶

Accesses the initial metadata emitted by the system under test.

This method blocks until the system under test has added initialmetadata to the RPC (or has provided one or more response messages orhas terminated the RPC, either of which will cause gRPC Python tosynthesize initial metadata for the RPC).

Returns:

The initial metadata for the RPC.

abstractrequests_closed()[source]¶

Indicates the end of the RPC’s request stream.

abstractsend_request(request)[source]¶

Sends a request to the system under test.

Parameters:

request – A request message for the RPC to be “sent” to the systemunder test.

abstracttermination()[source]¶

Blocks until the system under test has terminated the RPC.

Returns:

A (response, trailing_metadata, code, details) sequence with the RPC’s

response, trailing metadata, code, and details.

classgrpc_testing.Time[source]¶

A simulation of time.

Implementations needn’t be connected with real time as provided by thePython interpreter, but as long as systems under test useRpcContext.is_active and RpcContext.time_remaining for querying RPC livenessimplementations may be used to change passage of time in tests.

abstractcall_at(behavior,time)[source]¶

Adds a behavior to be called at a specific time.

Parameters:

• behavior – A behavior to be called with no arguments.

• time – The test time at which to call the behavior.

Returns:

A grpc.Future with which the call of the behavior may be cancelled

before it is executed.

abstractcall_in(behavior,delay)[source]¶

Adds a behavior to be called after some time.

Parameters:

• behavior – A behavior to be called with no arguments.

• delay – A duration of time in seconds after which to call the behavior.

Returns:

A grpc.Future with which the call of the behavior may be cancelled

before it is executed.

abstractsleep_for(duration)[source]¶

Blocks for some length of test time.

Parameters:

duration – A duration of test time in seconds for which to block.

abstractsleep_until(time)[source]¶

Blocks until some test time.

Parameters:

time – The test time until which to block.

abstracttime()[source]¶

Accesses the current test time.

Returns:

The current test time (over which this object has authority).

classgrpc_testing.UnaryStreamChannelRpc[source]¶

Fixture for a unary-stream RPC invoked by a system under test.

Enables users to “play server” for the RPC.

abstractcancelled()[source]¶

Blocks until the system under test has cancelled the RPC.

abstractsend_initial_metadata(initial_metadata)[source]¶

Sends the RPC’s initial metadata to the system under test.

Parameters:

initial_metadata – The RPC’s initial metadata to be “sent” tothe system under test.

abstractsend_response(response)[source]¶

Sends a response to the system under test.

Parameters:

response – A response message to be “sent” to the system under test.

abstractterminate(trailing_metadata,code,details)[source]¶

Terminates the RPC.

Parameters:

• trailing_metadata – The RPC’s trailing metadata.

• code – The RPC’s status code.

• details – The RPC’s status details.

classgrpc_testing.UnaryStreamServerRpc[source]¶

Fixture for a unary-stream RPC serviced by a system under test.

Enables users to “play client” for the RPC.

abstractcancel()[source]¶

Cancels the RPC.

abstractinitial_metadata()[source]¶

Accesses the initial metadata emitted by the system under test.

This method blocks until the system under test has added initialmetadata to the RPC (or has provided one or more response messages orhas terminated the RPC, either of which will cause gRPC Python tosynthesize initial metadata for the RPC).

Returns:

The initial metadata for the RPC.

abstracttake_response()[source]¶

Draws one of the responses added to the RPC by the system under test.

Successive calls to this method return responses in the same order inwhich the system under test added them to the RPC.

Returns:

A response message added to the RPC by the system under test.

abstracttermination()[source]¶

Blocks until the system under test has terminated the RPC.

Returns:

A (trailing_metadata, code, details) sequence with the RPC’s trailing

metadata, code, and details.

classgrpc_testing.UnaryUnaryChannelRpc[source]¶

Fixture for a unary-unary RPC invoked by a system under test.

Enables users to “play server” for the RPC.

abstractcancelled()[source]¶

Blocks until the system under test has cancelled the RPC.

abstractsend_initial_metadata(initial_metadata)[source]¶

Sends the RPC’s initial metadata to the system under test.

Parameters:

initial_metadata – The RPC’s initial metadata to be “sent” tothe system under test.

abstractterminate(response,trailing_metadata,code,details)[source]¶

Terminates the RPC.

Parameters:

• response – The response for the RPC.

• trailing_metadata – The RPC’s trailing metadata.

• code – The RPC’s status code.

• details – The RPC’s status details.

classgrpc_testing.UnaryUnaryServerRpc[source]¶

Fixture for a unary-unary RPC serviced by a system under test.

Enables users to “play client” for the RPC.

abstractcancel()[source]¶

Cancels the RPC.

abstractinitial_metadata()[source]¶

Accesses the initial metadata emitted by the system under test.

This method blocks until the system under test has added initialmetadata to the RPC (or has provided one or more response messages orhas terminated the RPC, either of which will cause gRPC Python tosynthesize initial metadata for the RPC).

Returns:

The initial metadata for the RPC.

abstracttermination()[source]¶

Blocks until the system under test has terminated the RPC.

Returns:

A (response, trailing_metadata, code, details) sequence with the RPC’s

response, trailing metadata, code, and details.

grpc_testing.channel(service_descriptors,time)[source]¶

Creates a Channel for use in tests of a gRPC Python-using system.

Parameters:

• service_descriptors – An iterable of descriptor.ServiceDescriptorsdescribing the RPCs that will be made on the returned Channel by thesystem under test.

• time – A Time to be used for tests.

Returns:

A Channel for use in tests.

grpc_testing.server_from_dictionary(descriptors_to_servicers,time)[source]¶

Creates a Server for use in tests of a gRPC Python-using system.

Parameters:

• descriptors_to_servicers – A dictionary from descriptor.ServiceDescriptorsdefining RPC services to servicer objects (usually instances of classesthat implement “Servicer” interfaces defined in generated “_pb2_grpc”modules) implementing those services.

• time – A Time to be used for tests.

Returns:

A Server for use in tests.

grpc_testing.strict_fake_time(now)[source]¶

Creates a Time that can be manipulated by test code.

The returned instance maintains an internal representation of timeindependent of real time. This internal representation only advanceswhen user code calls the instance’s sleep_for and sleep_until methods.

The returned instance will be “strict” with respect to callbackssubmitted to it: it will ensure that all callbacks registered tobe called at time t have been called before it describes the timeas having advanced beyond t.

Returns:

A Time that simulates the passage of time.

grpc_testing.strict_real_time()[source]¶

Creates a Time backed by the Python interpreter’s time.

The returned instance will be “strict” with respect to callbackssubmitted to it: it will ensure that all callbacks registered tobe called at time t have been called before it describes the timeas having advanced beyond t.

Returns:

A Time backed by the “system” (Python interpreter’s) time.