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 grpcurlOn Linux:
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latestVerify:
grpcurl --version
# grpcurl v1.9.1Discovering 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.PaymentServiceList methods on a specific service:
grpcurl -plaintext localhost:50051 list payment.PaymentService
# payment.PaymentService.ProcessPayment
# payment.PaymentService.GetPaymentStatus
# payment.PaymentService.StreamTransactionsDescribe 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/ProcessPaymentWith TLS (production):
grpcurl \
-d '{"order_id": "ord-123", "amount": 99.99, "currency": "USD", "customer_id": "cust-456"}' \
api.example.com:443 \
payment.PaymentService/ProcessPaymentWith 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/ProcessPaymentReading 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.jsonWhen 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/ProcessPaymentIf your proto imports other protos:
grpcurl -plaintext \
-import-path ./proto \
-proto payment/payment.proto \
-d '{"order_id": "ord-123"}' \
localhost:50051 \
payment.PaymentService/GetPaymentStatusTesting 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/StreamTransactionsTesting 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/BatchPaymentBloomRPC: 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
- Open BloomRPC
- Click the + button in the left panel
- Select your
.protofile(s) - 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
- Select a method from the left panel
- BloomRPC auto-generates a JSON template from the proto definition
- Fill in the values
- Set the server address (e.g.,
localhost:50051) - 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:
- Click Environments in the top bar
- Create environments with different server addresses and metadata
- Switch environments with a dropdown
Testing Streaming in BloomRPC
BloomRPC visualizes streaming responses in real-time. For server-streaming:
- Select a server-streaming method
- Send the request
- Watch responses appear in the response panel as they arrive
For bidirectional streaming:
- Select a bidirectional streaming method
- Click play to open the stream
- Manually send messages using the input panel
- 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 inputNOT_FOUND(5) — resource missingALREADY_EXISTS(6) — duplicatePERMISSION_DENIED(7) — auth failureUNAUTHENTICATED(16) — missing credentialsRESOURCE_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/ProcessPaymentDoes 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 responseScripting 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
-protoflag) - 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.