Chapter 6: Mocking and simulating gRPC

« Back to tutorials home

Mocking and simulating gRPC APIs using service virtualization

If you are new to the subject have a look at Chapter 1: Getting started with stubbing, mocking and service virtualization. If you know why and how to use mocking, simulating APIs and service virtualization, continue reading to learn how to do it for the gRPC remote procedure calls protocol. We will use mocking, simulating and service virtualization terms here interchangeably.

Useful terms to know

To fully grasp what we will be covering you should have a basic knowledge of software testing and understand what the following terms mean:

  • RPC: a remote procedure call is the act of connecting to a remote system using a particular protocol to carry out work and return the result to the calling system.
  • Protocol Buffers: a binary message format developed by Google.
  • Bidirectional streaming: the ability for the client and server to asynchronously send and receive multiple messages at the same time to each other

A quick refresh of gRPC

gRPC is an open source protocol used for remote procedure calls which was initially developed at Google. It uses HTTP/2 for transport and most typically uses Protocol Buffers to define a message schema. It provides features such as authentication, bidirectional streaming and blocking or nonblocking bindings. It is possible to generate cross-platform client and server code for many languages.

Development teams choose to use gRPC because:
  1. It is compatible with many popular languages such as Java, C++, Python and many more
  2. Schema driven messages mean that type safe boilerplate server and client code can be quickly generated rather than e.g. writing a custom client to parse a JSON message
  3. Messages can be versioned, providing a clean way to manage backwards compatibility with e.g. optional fields
  4. Bidirectional streaming opens up the possibility for more performant communication patterns between microservices

Two systems communicating using unary gRPC

It is possible to use gRPC in a manner very similar to standard HTTP, where a client sends a single request message to the server and the server responds with a single response message. This mode is referred to as "unary streaming" in gRPC. It can work very well for a large number of use cases where the performance benefit of bidirectional streaming is unnecessary.

Let us focus on a typical communication pattern where two systems communicate with unary gRPC request and responses:

  1. Client sends request message to server
  2. The client can choose whether to block and wait for the response or to receive the response asynchronously
  3. Server sends response message to client
gRPC unary communication

Mocking and simulating unary gRPC messages

It is typical for one team to develop a gRPC service that is consumed by one or more other teams. For example System A may contain a gRPC client that communicates with System B that contains a gRPC server. This introduces an issue: how can the client teams test their client system against the service system that does not exist yet?

Testing issue when the gRPC server is not available

To reduce the cost of delay, you can choose to simulate the gRPC service in System B before the service team have finished their implementation. By defining the API up front by using the proto file definitions, both the client and server teams can work in parallel.

Using Traffic Parrot mock gRPC server

With Traffic Parrot, you can take the proto API definition and use it to produce a virtual service that can mock and simulate gRPC responses. This way, your client team can test System A in isolation without having to wait for the server team to finish working on System B.

This will allow us to test System A in isolation in both typical and hypothetical situations. You will be able to simulate gRPC responses that are expected to be seen in production environments, but also non-typical error responses or failure scenarios that would usually be hard to reproduce. You can do that by configuring Traffic Parrot to respond with response messages of your choice.

Using Traffic Parrot to send gRPC response messages

Traffic Parrot supports using the proto API definition file to produce a mock service. You can use the user interface to define mock responses and simulate behaviour using the advanced templating features.

Let’s go through an example of how to simulate a gRPC service that is specified in the following proto:
message Item {
    int32 sku = 1;
    int32 quantity = 2;

enum Status {
    SUCCESS = 0;
    ERROR = 1;

message OrderStatus {
    Status status = 1;
    string message = 2;

service Order {
    rpc Purchase(Item) returns (OrderStatus) {}

The application we are testing is a simple shopping application that can be used to order items from a shop server:

Shopping application

The systems communicate using unary gRPC:

Shopping application communicates via gRPC

We can use Traffic Parrot instead of the real shop server:

Simulating (mocking) gRPC API using Traffic Parrot
To follow this example along you will need:
  1. Java version 8 or above. You can download it here.
  2. The shopping application (our system under test). You can download it here (sources are available on GitHub).
  3. The proto file of the gRPC shopping service. You can download it here.
  4. We will also need Traffic Parrot. You can download a trial version here.
Follow these steps to use the gRPC shopping application:
  1. Download and extract the shopping application.
  2. Start the shopping application by double clicking the start.cmd script on Windows (or running on Linux):
    Shopping application start script
  3. Try to place an order by clicking the order button. You will see that the application says the server is UNAVAILABLE:
    Shopping application unavailable
In order to test the shopping application without the server we will set up and use Traffic Parrot:
  1. Download and extract Traffic Parrot
  2. Provide a copy of the proto file to Traffic Parrot by downloading the proto file of the gRPC service and copying it into the proto directory:
    Copy proto file to Traffic Parrot
  3. Start Traffic Parrot by double clicking the start.cmd script on Windows (or running on Linux):
    Traffic Parrot start script
  4. Go to the gRPC Add/Edit page:
    Edit gRPC skeleton
  5. Click on the message skeleton to help us define a mapping
  6. Change the request "sku" and "quantity" to 1
  7. Change the response "message" to "Example message"
  8. Click the Save button
Now we can try to submit the order again:
  1. Change the server port to 5552 (the Traffic Parrot gRPC server port) and click the order button:
    Shopping application mock response
  2. You should see the success response with the message "Example message" that we edited earlier
  3. You can click the edit button on the Add/Edit page and change the mapping
  4. For example, change the response message and submit the order again. Traffic Parrot will return the new message to the shopping application.

Streaming modes

This tutorial has focused on the simple case where there is one request message and one response message.

However, with gRPC you benefit from HTTP/2 which means that you will have asynchronous streaming support.

The possible streaming modes are:
  • Unary: client sends a single request message and server replies with a single response message
  • Server Streaming: client sends a single request message and server replies with a stream of response messages
  • Client Streaming: client streams request messages and server replies with a single response message
  • Bidirectional Streaming: client streams request messages and server replies with a stream of response messages

Traffic Parrot currently has full support for unary streaming mode and partial support for the server and bidirectional streaming modes. For more information see the gRPC documentation.

Next steps