1. Home
  2. Documentation
  3. gRPC

gRPC

« Back to documentation home

gRPC virtual service architecture

A developer or tester uses a web browser to access the console. The console manages the virtual service. The system under test (application under test) connects directly to the virtual service on different ports.
gRPC architecture

Configuration

Proto files

Traffic Parrot needs to know about the schema of your messages.

One way to do this is to provide your protocol buffer files. We currently support the proto3 specification.

To do this, simply copy your .proto files into the trafficparrot-enterprise-release-x.y.z/proto directory and Traffic Parrot will use these definitions during record/replay.

Server reflection

Traffic Parrot can discover the schema of your messages during recording if you have server reflection enabled in your gRPC server.

Discovered schemas are saved in the trafficparrot-enterprise-release-x.y.z/proto-bin directory and are used during replay.

To enable server reflection please follow the instructions for your gRPC server language:

SSL/TLS

Typically, gRPC is authenticated using SSL/TLS

Traffic Parrot has the following properties that can be used to configure SSL/TLS:
  • trafficparrot.virtualservice.grpc.tls.port
    The port number to use when recording/replaying TLS traffic (default 5551)
  • trafficparrot.virtualservice.grpc.requireClientAuthentication
    Set to true when client authentication is required and false otherwise
  • trafficparrot.virtualservice.grpc.serverTrustPemUrl
    X.509 certificate collection file in PEM format that will be trusted by the virtual gRPC server
  • trafficparrot.virtualservice.grpc.serverPemUrl
    X.509 certificate chain file in PEM format that will be the public key of the virtual gRPC server
  • trafficparrot.virtualservice.grpc.serverKeyUrl
    PKCS#8 private key file in PEM format that will be the private key of the virtual gRPC server
  • trafficparrot.virtualservice.grpc.clientTrustPemUrl
    X.509 certificate collection file in PEM format that will be trusted by the virtual gRPC client
  • trafficparrot.virtualservice.grpc.clientOverrideAuthority
    Overrides the authority used with TLS and HTTP virtual hosting. It does not change what host is actually connected to. Is commonly in the form host:port
If client authentication is required use the following additional properties:
  • trafficparrot.virtualservice.grpc.clientPemUrl
    X.509 certificate chain file in PEM format that will be the public key of the virtual gRPC client
  • trafficparrot.virtualservice.grpc.clientKeyUrl
    PKCS#8 private key file in PEM format that will be the private key of the virtual gRPC client

The URL property values can be set to classpath entries e.g. classpath:certificates/grpc/server.pem

By default Traffic Parrot has properties that correspond to the certificates found in the trafficparrot-enterprise-release-x.y.z/certificates/grpc directory.

Alternatively, you can specify file URL entries e.g. file:///path/to/server.pem

The property trafficparrot.virtualservice.grpc.non.tls.port specifies a port that can be used if SSL/TLS is not required (default 5552).

Performance

The following properties have a significant impact on gRPC performance during replay:

Property Description
trafficparrot.virtualservice.grpc.server.replay.proto.cache.milliseconds Proto files can be cached in memory during replay to improve performance. The default value of 0 means do not cache at all.
trafficparrot.virtualservice.grpc.server.replay.proto.cache.populate.on.startup When true the proto file cache will be populated immediately on startup.
trafficparrot.virtualservice.mapping.cache.milliseconds Mapping files can be cached in memory during replay to improve performance. The default value of 0 means do not cache at all.
trafficparrot.virtualservice.mapping.cache.populate.on.startup When true the mapping file cache will be populated immediately on startup.
trafficparrot.virtualservice.grpc.server.boss.threads The number of boss threads used to service gRPC requests. Typically best set to either DOUBLE_NUMBER_OF_PROCESSORS or NUMBER_OF_PROCESSORS based on the number of available processors the system has.
trafficparrot.virtualservice.grpc.server.boss.threads The number of worker threads used to service gRPC requests. Typically best set to either DOUBLE_NUMBER_OF_PROCESSORS or NUMBER_OF_PROCESSORS based on the number of available processors the system has.

Recording and replaying gRPC

Introduction

During recording, incoming and outgoing messages are matched up to provide mappings. Then upon playback receipt of a matching incoming message will trigger generation of an outgoing message.

This diagram shows how two production systems connect:
gRPC unary communication

One system sends a gRPC request message to another system, which consumes the messages and returns a gRPC response message to the first system. If our goal is to test the system-under-test in isolation, we must record these interactions in order to replay them.

Recording and replaying gRPC messages using provided proto files

As you can see in the diagram below, the virtual service acts as a proxy between the gRPC client and gRPC server. The provided proto files are used to determine the message schema of the request and response messages for the requested gRPC method. Mappings are saved representing request/response pairs that have been recorded.

Recording gRPC messages using provided proto files
Steps to perform a recording using provided proto files
  1. Start Traffic Parrot
  2. Configure Traffic Parrot with your proto files
  3. Go to the gRPC record page
  4. Enter the host and port of the gRPC server to record
  5. Click "Start recording"
  6. Reconfigure your system under test to connect to the virtual service gRPC server (by default this is localhost:5552)
  7. Execute a test case to allow Traffic Parrot to record requests and responses. They will appear on the Messages and Mappings lists on the web page as shown on Mappings and messages lists during recording image.
  8. Click "Stop recording"

As the system under test generates messages and receives responses they are paired into mappings and listed in the 'Mappings' table.

Mappings list during a gRPC recording

On replay, the provided proto files are again used to determine the schema of the requested gRPC method. The request is matched against the mappings to find the corresponding response message.

Replaying gRPC messages using provided proto files
Steps to perform a replay using provided proto files
  1. Start Traffic Parrot
  2. Configure Traffic Parrot with your proto files
  3. Reconfigure your system under test to connect to the virtual service gRPC server (by default this is localhost:5552)
  4. Traffic Parrot will replay recorded mappings when it is not in record mode

Recording and replaying gRPC messages using gRPC server reflection

As you can see in the diagram below, the virtual service acts as a proxy between the gRPC client and gRPC server. Server reflection is used to pull the proto files definitions from the gRPC server for the requested gRPC method. These proto files are saved for later use during replay. Mappings are saved representing request/response pairs that have been recorded.

Recording gRPC messages using gRPC server reflection
Steps to perform a recording using gRPC server reflection
  1. Start Traffic Parrot
  2. Go to the gRPC record page
  3. Enter the host and port of the gRPC server to record
  4. Click "Start recording"
  5. Reconfigure your system under test to connect to the virtual service gRPC server (by default this is localhost:5552)
  6. Execute a test case to allow Traffic Parrot to record requests and responses. They will appear on the Messages and Mappings lists on the web page as shown on Mappings and messages lists during recording image.
  7. Click "Stop recording"

As the system under test generates messages and receives responses they are paired into mappings and listed in the 'Mappings' table.

Mappings list during a gRPC recording

On replay, the recored proto files used to determine the schema of the requested gRPC method. The request is matched against the mappings to find the corresponding response message.

Replaying gRPC messages using recorded proto files
Steps to perform a replay using provided proto files
  1. Start Traffic Parrot
  2. Reconfigure your system under test to connect to the virtual service gRPC server (by default this is localhost:5552)
  3. Traffic Parrot will replay recorded mappings when it is not in record mode

Add/Edit gRPC mappings

Usage

First, go to gRPC in the top navigation bar and click Add/Edit.

Add gRPC mapping screenshot

Fill in the Request/Response fields and click Save to configure a mapping.

You can also select from the message skeleton dropdown which will populate the Request/Response fields with a message skeleton for that message type.

After saving the mapping, it will appear in the list of mappings.

gRPC mapping list

Clicking the edit button will allow you to edit an existing mapping.

The request and response body can be edited as if they were a JSON body. You are free to change the JSON as you wish, so long as the edits are compatible with the underlying proto message schema that the JSON represents.

Edit gRPC mapping screenshot

Edit gRPC status exception screenshot

Supported features
  • Edit status code and message for StatusRuntimeException responses
  • Edit exception metadata, using either simple key: value pairs or a details object
  • Edit response message values
  • Edit response message structure (e.g. delete optional fields, add items to list, add nested fields)
  • Use helpers in the response body
  • Use parts of the request message in the response message by extracting with JsonPath
  • Match request messages using the request body matchers (e.g. JsonPath, contains, regexp) on the JSON representation of the message
  • Match request messages by key: value pairs in the request metadata
  • Use priority to set up a preference order for matching mappings
Currently, editing non-exception metadata is not yet possible. Please contact support@trafficparrot.com to be notified of when this functionality is ready.

Exception Details Object

gRPC allows for returning one or more custom detail objects in exception responses. Traffic Parrot currently supports specifying a single details object:

Edit gRPC exception details object screenshot

You must specify the fully qualified type e.g. com.example.Details as well as the JSON representation of the object.

Priority

The request priority can be set in order to set up a preference order for matching mappings.

The highest priority value is 1. If two or more mappings both match a request, the mapping with the higher priority will be used to provide the response. The default priority is 5.

This can be useful, if you want a "catch-all" mapping that returns a general response for most requests and specific mappings on top that return more specific responses.

Request Metadata

Request metadata can be specified as key: value pairs. This means that Traffic Parrot will only match requests that contain the specified metadata values.

You can use the property trafficparrot.virtualservice.grpc.exclude.request.headers.from.matching to exclude request headers from matching. For example typical headers such as content-type,user-agent,grpc-accept-encoding are not typically useful to match on.

Configuring message skeletons

To populate the list of message skeletons, you need to configure Traffic Parrot with your proto files.

Then you can select the name of a gRPC method from the list and a sample request and response value will be generated, containing the default values for the message.

gRPC skeleton

gRPC streaming modes

Introduction

Traffic Parrot currently supports the following gRPC streaming modes:
  • Unary RPC
  • Server streaming RPC
Please contact support@trafficparrot.com to be notified when other streaming modes are supported.

Unary RPC

In this mode:
  • There is one request and one response per RPC call.
  • Traffic Parrot represents this as a single request/response mapping.

Server streaming RPC

In this mode:
  • There is one request and multiple responses per RPC call.
  • Traffic Parrot represents this as multiple request/response mappings.
  • Each mapping has a MessageNumber in the mapping file that represents the order of the responses.
  • Each mapping has a CallId in the mapping file that represents which RPC call the mapping belongs to.
  • The request matcher is duplicated for each mapping.

Proof of concept with on-premises installation at a large enterprise

See proof of concept in the user guide.

Dynamic responses and custom extensions

Have a look at available custom extensions and how to generate responses dynamically

Old version warning!

This documentation is for an old version of Traffic Parrot. There is a more recent Traffic Parrot version available for download at trafficparrot.com

Browse documentation for recent version