Quick start
gRPC virtual service 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
- 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/lib/virtualservice-x.y.z/virtualservice-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).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:
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.
Steps to perform a recording using provided proto files
- Start Traffic Parrot
- Configure Traffic Parrot with your proto files
- Go to the gRPC record page
- Enter the host and port of the gRPC server to record
- Click "Start recording"
- Reconfigure your system under test to connect to the virtual service gRPC server (by default this is localhost:5552)
- 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.
- Click "Stop recording"
As the system under test generates messages and receives responses they are paired into mappings and listed in the 'Mappings' table.
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.
Steps to perform a replay using provided proto files
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.
Steps to perform a recording using gRPC server reflection
- Start Traffic Parrot
- Go to the gRPC record page
- Enter the host and port of the gRPC server to record
- Click "Start recording"
- Reconfigure your system under test to connect to the virtual service gRPC server (by default this is localhost:5552)
- 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.
- Click "Stop recording"
As the system under test generates messages and receives responses they are paired into mappings and listed in the 'Mappings' table.
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.
Steps to perform a replay using provided proto files
- Start Traffic Parrot
- Reconfigure your system under test to connect to the virtual service gRPC server (by default this is localhost:5552)
- Traffic Parrot will replay recorded mappings when it is not in record mode
Edit gRPC mappings
Introduction
will allow you to edit an existing mapping:
- Add/Edit
- Record
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.
Supported features
- 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
gRPC streaming modes
Introduction
Traffic Parrot currently supports the following gRPC streaming modes:- Unary RPC
- Server streaming RPC
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.