title: “88. Using grpcurl for Manual Testing” date: 2024-06-20T12:00:00Z tags: [grpc, testing, cli, productivity, tutorial] cover_image: https://miro.medium.com/v2/resize:fit:1400/1 *0UvK7Uv0LpD_gQE7IJzFNw.png

88. Using grpcurl for Manual Testing

Testing is an integral part of application development, especially when we’re talking about communication protocols like gRPC. However, testing a gRPC service can often turn into a nightmare—the setup is too complicated, you have to write a lot of “dummy client” code, or you even stumble over obscure dependencies just to make sure the service behaves the way you intended. This is exactly where grpcurl comes in as a game changer.

In this article, I want to share my experience and best practices for using grpcurl for manual testing of gRPC services, complete with hands-on examples, simulations, and even a small flow diagram to clarify the workflow I use day to day as an engineer.

What Is grpcurl?

grpcurl is an open-source CLI tool that lets us communicate directly with a gRPC server. It works much like curl—except it’s for gRPC. With this tool, you can inspect, call, and debug gRPC endpoints without having to write any dedicated client code.

Why Do You Need grpcurl?

• No Client Code Required: All you need is a terminal and you can already perform calls.
• Dynamic: It supports the reflection protocol, so you don’t necessarily need a .proto file.
• Automation: It can be combined with bash scripts or a CI pipeline.
• Interactive: It’s easy to explore parameters and responses.

Quick Installation

1# For Mac (Homebrew)
2brew install grpcurl
3
4# For Linux
5sudo apt install protobuf-compiler
6GO111MODULE=on go get github.com/fullstorydev/grpcurl/cmd/grpcurl

Verify the installation with:

1grpcurl --version

Step 1: Getting to Know the Service

Before testing, make sure you know which endpoints are available on the server. If the server supports reflection, run the following command:

1grpcurl <host>:<port> list

Example output:

1helloworld.Greeter
2userprofile.UserService

To find out the methods of a specific service:

1grpcurl <host>:<port> list userprofile.UserService

Output:

1userprofile.UserService.GetUser
2userprofile.UserService.UpdateUser
3userprofile.UserService.ListUsers

Step 2: Showing Method Details

To learn the input/output of a method, use describe:

1grpcurl <host>:<port> describe userprofile.UserService.GetUser

Example output:

1rpc GetUser (GetUserRequest) returns (User) {
2}

Step 3: Making a Call (Without .proto)

If the server supports reflection—all you need is JSON, and you can already invoke the RPC.

1grpcurl -d '{
2  "user_id": "u123"
3}' <host>:<port> userprofile.UserService.GetUser

The result:

1{
2  "user_id": "u123",
3  "name": "John",
4  "email": "john@mail.com"
5}

When Reflection Is Not Available (You Must Use .proto)

Sometimes a secure product or a production environment deliberately disables reflection. Don’t worry, grpcurl can use a local .proto file:

1grpcurl -import-path . -proto userprofile.proto \
2  -d '{"user_id": "u123"}' \
3  <host>:<port> userprofile.UserService.GetUser

Flow Diagram: Manual Testing Workflow

flowchart TD
    A[Mulai] --> B{GRPC Reflection Tersedia?}
    B -- Ya --> C[Langsung grpcurl endpoint]
    B -- Tidak --> D[Pakai .proto lokal]
    C --> E[Panggil method dengan data]
    D --> E
    E --> F[Lihat hasil]
    F --> G{Perlu Testing Lanjut?}
    G -- Ya --> E
    G -- Tidak --> H[Selesai]

flowchart TD
    A[Mulai] --> B{GRPC Reflection Tersedia?}
    B -- Ya --> C[Langsung grpcurl endpoint]
    B -- Tidak --> D[Pakai .proto lokal]
    C --> E[Panggil method dengan data]
    D --> E
    E --> F[Lihat hasil]
    F --> G{Perlu Testing Lanjut?}
    G -- Ya --> E
    G -- Tidak --> H[Selesai]

The diagram above closely mirrors my habits when debugging a new gRPC service for a client or another team.

Simulation Example: End-to-End Workflow

Assumption: There is a UserService with a CreateUser endpoint.

1. Listing the Endpoints

1grpcurl localhost:50051 list

2. View the Details of CreateUser

1grpcurl localhost:50051 describe userprofile.UserService.CreateUser

3. Start Testing CreateUser

1grpcurl -d '{
2  "name": "Alice",
3  "email": "alice@mail.com"
4}' localhost:50051 userprofile.UserService.CreateUser

Output:

1{
2  "user_id": "u124",
3  "name": "Alice",
4  "email": "alice@mail.com"
5}

4. Simulating an Error Case

Try sending a request without an email:

1grpcurl -d '{
2  "name": "Bob"
3}' localhost:50051 userprofile.UserService.CreateUser

Output:

1ERROR:
2  Code: InvalidArgument
3  Message: email is required

5. Comparison Table: grpcurl vs. Writing a Client

Tips & Best Practices

• Test automation: Drop grpcurl into a bash script for regression/CI pipelines.
• Environment variables: Store the host/port in ENV to make things easier.
• Handle Auth/TLS: grpcurl supports authentication and certificates, check the docs .
• Documentation: Attach the description output to your team’s internal documentation.
• Testing Negative Cases: Don’t forget to test invalid input, edge cases, and errors!

Conclusion

grpcurl is incredibly powerful at crushing the “How do I test this gRPC service?” problem without having to constantly write or rebuild dummy client code. You can explore the API, debug, and even automate regression checks with nothing but a terminal. For engineers who frequently work at the integration and system level, grpcurl is a must-have in your toolbelt.

Note: gRPC is the future of modern APIs; the right tooling will help you innovate faster.

I hope this helps boost the productivity of your manual gRPC service testing. Feel free to share your experience with other CLI tools in the comments! 🚀

References:

• grpcurl GitHub
• gRPC Official
• Medium Engineer Style Guide