gRPC Testing Fundamentals: grpcurl & BloomRPC Deep Dive

gRPC Testing Fundamentals: grpcurl & BloomRPC Deep Dive

gRPC services are notoriously harder to test than REST APIs. There's no browser URL bar, no Postman equivalent that just works out of the box, and reflection isn't always enabled. This guide covers the two most practical tools for manual gRPC testing: grpcurl (CLI-based) and BloomRPC (GUI-based), with real workflows you can apply immediately.

Why gRPC Testing Is Different

gRPC uses Protocol Buffers over HTTP/2. That means:

  • Binary wire format — you can't inspect traffic with a simple tcpdump
  • Strongly typed contracts — mismatched field types fail at the proto layer, not HTTP
  • Multiplexed streams — connection behavior differs from REST
  • Server reflection — optional, but makes tooling much easier

Before you can test anything, you need to understand what the service exposes. That's where grpcurl and BloomRPC shine.

Setting Up grpcurl

Install grpcurl on macOS:

brew install grpcurl

On Linux:

go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest

Verify:

grpcurl --version
# grpcurl v1.9.1

Discovering Services with grpcurl

If your gRPC server has reflection enabled, discovery is straightforward:

# List all services
grpcurl -plaintext localhost:50051 list

# Example output:
# grpc.reflection.v1alpha.ServerReflection
# helloworld.Greeter
# payment.PaymentService

List methods on a specific service:

grpcurl -plaintext localhost:50051 list payment.PaymentService

# payment.PaymentService.ProcessPayment
# payment.PaymentService.GetPaymentStatus
# payment.PaymentService.StreamTransactions

Describe a method to see its input/output types:

grpcurl -plaintext localhost:50051 describe payment.PaymentService.ProcessPayment

# payment.PaymentService.ProcessPayment is a method:
# rpc ProcessPayment ( .payment.PaymentRequest ) returns ( .payment.PaymentResponse );

Describe the request type:

grpcurl -plaintext localhost:50051 describe payment.PaymentRequest

# payment.PaymentRequest is a message:
# message PaymentRequest {
#   string order_id = 1;
#   double amount = 2;
#   string currency = 3;
#   string customer_id = 4;
# }

Sending Requests with grpcurl

Basic unary call:

grpcurl -plaintext \
  -d '{"order_id": "ord-123", "amount": 99.99, "currency": "USD", "customer_id": "cust-456"}' \
  localhost:50051 \
  payment.PaymentService/ProcessPayment

With TLS (production):

grpcurl \
  -d '{"order_id": "ord-123", "amount": 99.99, "currency": "USD", "customer_id": "cust-456"}' \
  api.example.com:443 \
  payment.PaymentService/ProcessPayment

With metadata headers (authentication):

grpcurl -plaintext \
  -H "authorization: Bearer eyJhbGc..." \
  -d '{"order_id": "ord-123", "amount": 99.99, "currency": "USD", "customer_id": "cust-456"}' \
  localhost:50051 \
  payment.PaymentService/ProcessPayment

Reading request data from a file:

# request.json
{
  "order_id": "ord-123",
  "amount": 99.99,
  "currency": "USD",
  "customer_id": "cust-456"
}

grpcurl -plaintext \
  -d @ \
  localhost:50051 \
  payment.PaymentService/ProcessPayment < request.json

When Reflection Is Disabled

Most production services don't enable reflection for security reasons. In that case, provide proto files directly:

grpcurl -plaintext \
  -proto ./proto/payment.proto \
  -d '{"order_id": "ord-123", "amount": 99.99, "currency": "USD", "customer_id": "cust-456"}' \
  localhost:50051 \
  payment.PaymentService/ProcessPayment

If your proto imports other protos:

grpcurl -plaintext \
  -import-path ./proto \
  -proto payment/payment.proto \
  -d '{"order_id": "ord-123"}' \
  localhost:50051 \
  payment.PaymentService/GetPaymentStatus

Testing Server-Streaming with grpcurl

Server-streaming RPCs return multiple responses. grpcurl handles this automatically — it streams output until the server closes the connection:

grpcurl -plaintext \
  -d '{"customer_id": "cust-456", "limit": 10}' \
  localhost:50051 \
  payment.PaymentService/StreamTransactions

# Each response is printed as it arrives:
# {
#   "transaction_id": "txn-001",
#   "amount": 25.00,
#   "timestamp": "2026-01-15T10:30:00Z"
# }
# {
#   "transaction_id": "txn-002",
#   "amount": 150.00,
#   "timestamp": "2026-01-15T11:00:00Z"
# }

Add a timeout to avoid hanging on misbehaving streams:

grpcurl -plaintext \
  -max-time 30 \
  -d '{"customer_id": "cust-456", "limit": 10}' \
  localhost:50051 \
  payment.PaymentService/StreamTransactions

Testing Client-Streaming with grpcurl

For client-streaming RPCs, pipe newline-delimited JSON:

echo -e '{"amount": 10.0, "currency": "USD"}\n{"amount": 20.0, "currency": "EUR"}' | \
  grpcurl -plaintext \
  -d @ \
  localhost:50051 \
  payment.PaymentService/BatchPayment

BloomRPC: GUI-Based gRPC Testing

BloomRPC provides a Postman-like interface for gRPC. It's particularly useful when:

  • You're exploring a new service and want to browse methods visually
  • Team members aren't comfortable with CLI tools
  • You want to save and share request collections

Installing BloomRPC

Download from the BloomRPC GitHub releases. Available for macOS, Windows, and Linux.

Importing Proto Files

  1. Open BloomRPC
  2. Click the + button in the left panel
  3. Select your .proto file(s)
  4. BloomRPC parses the file and lists all services and methods

For services with reflection, click Import from server reflection and enter the server address.

Making Requests in BloomRPC

  1. Select a method from the left panel
  2. BloomRPC auto-generates a JSON template from the proto definition
  3. Fill in the values
  4. Set the server address (e.g., localhost:50051)
  5. Click the play button

BloomRPC shows both the request and response in split panels, making it easy to inspect the structure.

Managing Environments

BloomRPC supports environments for switching between local, staging, and production:

  1. Click Environments in the top bar
  2. Create environments with different server addresses and metadata
  3. Switch environments with a dropdown

Testing Streaming in BloomRPC

BloomRPC visualizes streaming responses in real-time. For server-streaming:

  1. Select a server-streaming method
  2. Send the request
  3. Watch responses appear in the response panel as they arrive

For bidirectional streaming:

  1. Select a bidirectional streaming method
  2. Click play to open the stream
  3. Manually send messages using the input panel
  4. Observe responses as they come back

Common Testing Scenarios

Testing Error Handling

gRPC errors use status codes, not HTTP codes. Test error paths explicitly:

# Send invalid data to trigger validation errors
grpcurl -plaintext \
  -d '{"order_id": "", "amount": -1.0, "currency": "INVALID"}' \
  localhost:50051 \
  payment.PaymentService/ProcessPayment

# Expected: gRPC status INVALID_ARGUMENT
# {
#   "code": 3,
#   "message": "amount must be positive"
# }

gRPC status codes to test:

  • INVALID_ARGUMENT (3) — bad input
  • NOT_FOUND (5) — resource missing
  • ALREADY_EXISTS (6) — duplicate
  • PERMISSION_DENIED (7) — auth failure
  • UNAUTHENTICATED (16) — missing credentials
  • RESOURCE_EXHAUSTED (8) — rate limited

Testing with Empty Requests

Proto3 allows all fields to be optional with zero values as defaults. Test behavior with minimal input:

grpcurl -plaintext \
  -d '{}' \
  localhost:50051 \
  payment.PaymentService/ProcessPayment

Does the service handle missing required fields gracefully, or does it crash?

Verbose Output for Debugging

Get full request/response details including headers:

grpcurl -plaintext -v \
  -d '{"order_id": "ord-123", "amount": 99.99, "currency": "USD", "customer_id": "cust-456"}' \
  localhost:50051 \
  payment.PaymentService/ProcessPayment

# Output includes:
# Resolved method descriptor...
# Request metadata to send:
# Response headers received:
# Response contents:
# Response trailers received:
# Sent 1 request and received 1 response

Scripting grpcurl for Automation

grpcurl integrates naturally into shell scripts and CI pipelines:

#!/bin/bash

GRPC_SERVER="localhost:50051"
RESPONSE=$(grpcurl -plaintext \
  -d '{"order_id": "ord-test-001", "amount": 1.00, "currency": "USD", "customer_id": "cust-test"}' \
  "$GRPC_SERVER" \
  payment.PaymentService/ProcessPayment)

# Parse response with jq
STATUS=$(echo "$RESPONSE" | jq -r '.status')

if [ "$STATUS" != "SUCCESS" ]; then
  echo "FAIL: Expected SUCCESS, got $STATUS"
  exit 1
fi

echo "PASS: Payment processed successfully"

Integrating with HelpMeTest

For continuous monitoring of your gRPC service health, you can write gRPC smoke tests in plain English using HelpMeTest. Define what a healthy service response looks like, and HelpMeTest runs checks on a schedule — no infrastructure to manage, no scripts to maintain.

The tool handles the test execution loop while you focus on what "healthy" means for your specific service.

Key Takeaways

grpcurl is your go-to for:

  • Quick CLI-based testing and scripting
  • CI pipeline integration
  • Services without reflection (use -proto flag)
  • Streaming RPC testing

BloomRPC is your go-to for:

  • Visual exploration of new services
  • Sharing test scenarios with non-CLI users
  • Bidirectional streaming interaction
  • Saved request collections

Both tools work without writing application code, making them essential for any team working with gRPC services. Start with reflection-enabled local development, then add proto files for production testing.

Read more

Start now free