2 Good Tools To Test gRPC Server Applications

In this post, we’ll see how to test gRPC Server applications using different clients. And this post is not just for gRPC in ASP.NET Core but these tools can work with any gRPC servers written in any programming language.

In my previous post, we explored the gRPC project in ASP.NET Core and we looked at what is a proto file and why we need those field numbers in the proto files.

We also tried to run the gRPC service but it requires a specialized client to run it. We couldn’t see anything there.

Clients to test a gRPC server

There are several clients available online to test a gRPC server. In this post, I’m only going through the following clients which are notable and support server reflection.

• Postman
• gRPCurl

Before we begin testing, here is my server app running.

What is server reflection?

Server reflection gives information about the publicly accessible gRPC server endpoints and signatures. So, the clients can see what the server permits and how to query/run the endpoint.

The server reflection should be configured in the gRPC server application. For now, I haven’t configured the app to use server reflection.

Testing with postman

Postman is an API platform primarily used by developers/testers to test API’s. It has been in the industry for a decade now.

Install Postman by visiting their download page.

You don’t have to signup or login to your account for a normal HTTP request in Postman but to make a gRPC request you have to.

Once you are logged in, navigate to workspaces or create one if you don’t have one.

Without server reflection

Open Postman and we should select new and select the gRPC Request button in the create new modal. This should show the template for gRPC request.

Now for the server URL, we can enter the localhost URL of our app. For the “Select a method” we have three different options here.

• Use a Protobuf API
• Import a .proto file
• Use Server Reflection

If the server reflection is not available or not configured in our gRPC server we can manually attach the proto files using the “Import a .proto file” option.

As we haven’t configured server reflection yet let’s attach the proto file using this option. Now, this should ask you to enter a URL of where the proto file is located or you can choose to upload the proto file from your computer.

Once the path is selected, click on Next

In this step, you can persist your proto file within Postman to reuse it later. You can give a name and persist or just select “User without importing”

Once we have done that we should see our SayHello method, which is read after we have imported our proto file.

Now, we can make a request and we should see a response.

Great! We are able to make a request and able to see the response from our server. Now, let’s use the server reflection to let the client discover the server methods.

Setup gRPC reflection in ASP.NET Core

To set up server reflection in ASP.NET Core gRPC projects, we have to add Grpc.AspNetCore.Server.Reflection nuget package to our project.

Once we did that, we have to register the AddGrpcReflection method to enable reflection and MapGrpcReflectionService to add the reflection service endpoint.

builder.Services.AddGrpc();
builder.Services.AddGrpcReflection();

var app = builder.Build();

// Configure the HTTP request pipeline.
app.MapGrpcService<GreeterService>();
app.MapGet("/", () => "Communication with gRPC endpoints must be made through a gRPC client. To learn how to create a client, visit: https://go.microsoft.com/fwlink/?linkid=2086909");
app.MapGrpcReflectionService();

Now with the gRPC reflection setup for our gRPC project, let’s use server reflection to query the available methods in the gRPC server.

With server reflection in Postman

With server reflection enabled, we can get rid of importing the proto files manually in Postman.

Once we click the server reflection, our grpc server will provide methods that the client can invoke.

All we do is select the method and pass in the parameters to get some response.

Testing with gRPCurl

gRPCurl is a command line tool to test the grpc server endpoints.

Installing gRPC Curl

To install gRPC curl on a Mac, it’s fairly simple with Homebrew. Just run the following command

brew install grpcurl

By default, the grpcurl creators did not create a package for every platform. But, thanks to repology for maintaining all the archives and packages.

To install the gRPCurl on Windows, find a .zip file on the repology website that suits your CPU architecture x86 or x64.

Once the zip file is downloaded, unzip the file and you can run the grpcurl.exe with the arguments or you can add this grpcurl.exe to the path variable in environment variables to make it available for the command line.

Invoke a gRPC server with gRPCurl

Invoking a gRPC server could be done in two ways

• Without server reflection (requires passing the proto file manually)
• With server reflection (no need to pass the proto files)

gRPCurl Without server reflection

I’ve removed the server reflection from the app for this example. Let’s see how we can make a request by manually passing the proto file

grpcurl.exe -d '{"name": "Karthik"}' -plaintext -import-path ..\\GRPC\\GrpcTester\\Protos\\ -proto greet.proto localhost:5092 greet.Greeter/SayHello

And with the HTTPS endpoint we do this

grpcurl.exe -d '{"name": "Karthik"}' -import-path ..\\GRPC\\GrpcTester\\Protos\\ -proto greet.proto localhost:7092 greet.Greeter/SayHello

Though both of these requests produce the same result, notice how we invoke the HTTP and HTTPS requests. The HTTP request should use -plaintext as an argument and the HTTPS request is not using the -plaintext.

To see what we have in our service we can use describe parameter on the grpcurl command:

grpcurl.exe -import-path ..\\GRPC\\GrpcTester\\Protos\\ -proto greet.proto localhost:7092 describe

and here is the output:

greet.Greeter is a service:
// The greeting service definition.
service Greeter {
  // Sends a greeting
  rpc SayHello ( .greet.HelloRequest ) returns ( .greet.HelloReply );
}

The service definition is produced from our proto file as we’ve passed it in.

To get the server reflections from the endpoint, we have the following command. We use the list option on the command.

grpcurl --plaintext localhost:5092 list

This produces the following output.

Failed to list services: server does not support the reflection API

gRPCurl With Server Reflection Enabled

Once the server reflection is enabled, this is how we will make the request without passing the proto file.

grpcurl.exe -d '{ "name": "karthik" }' localhost:7092 greet.Greeter/SayHello

This should produce the following output in the console (Note that 7092 is HTTPS endpoint and not HTTP endpoint)

{
  "message": "Hello karthik"
}

If you were to use a non-HTTPS endpoint you could add the -plaintext argument to the command. Here it is.

grpcurl.exe -plaintext -d '{ "name": "karthik" }' localhost:5092 greet.Greeter/SayHello

Other Notable Tool

grpcui: This grpcUi tool requires two steps to test our gRPC server application. To get to the UI part, we have to run a command which hosts the UI on a port on localhost. I’m better off running a single grpcurl command to test the app.

References

• gRPC Testing tools
• gRPCurl
• gRPCurl on repology.org
• gRPCUi