gRPC Streaming Testing Patterns: Unary, Server-Side, and Bidirectional
gRPC offers four communication patterns, and testing each one requires a different approach. Most teams test unary calls and assume streaming works. That assumption breaks in production when stream management, backpressure, or error propagation behaves differently than expected. This guide covers testing all four patterns with practical examples.
The Four gRPC Patterns
Before writing tests, understand what you're testing:
| Pattern | Client sends | Server sends | Use case |
|---|---|---|---|
| Unary | One request | One response | Standard RPC calls |
| Server streaming | One request | Multiple responses | Real-time feeds, large datasets |
| Client streaming | Multiple requests | One response | Batch uploads, aggregation |
| Bidirectional streaming | Multiple requests | Multiple responses | Chat, real-time collaboration |
Each pattern has unique failure modes that unit tests must cover.
Proto Definition for Examples
syntax = "proto3";
package streaming.v1;
service StreamingService {
// Unary
rpc GetItem (ItemRequest) returns (ItemResponse);
// Server streaming
rpc WatchItems (WatchRequest) returns (stream ItemEvent);
// Client streaming
rpc BatchUpload (stream UploadRequest) returns (BatchResult);
// Bidirectional streaming
rpc Chat (stream ChatMessage) returns (stream ChatMessage);
}
message ItemRequest { string item_id = 1; }
message ItemResponse { string item_id = 1; string data = 2; }
message WatchRequest { string filter = 1; }
message ItemEvent { string event_type = 1; string item_id = 2; string data = 3; }
message UploadRequest { bytes content = 1; string filename = 2; }
message BatchResult { int32 uploaded = 1; int32 failed = 2; repeated string errors = 3; }
message ChatMessage { string sender = 1; string content = 2; int64 timestamp = 3; }Testing Unary RPCs
Unary tests are straightforward — send a request, assert a response:
package streaming_test
import (
"context"
"testing"
"time"
"github.com/stretchr/testify/assert"
"github.com/stretchr/testify/require"
"google.golang.org/grpc"
"google.golang.org/grpc/codes"
"google.golang.org/grpc/credentials/insecure"
"google.golang.org/grpc/status"
streamingv1 "example.com/proto/streaming/v1"
)
func setupTestClient(t *testing.T, server *grpc.Server) streamingv1.StreamingServiceClient {
t.Helper()
lis, err := net.Listen("tcp", "localhost:0")
require.NoError(t, err)
go server.Serve(lis)
t.Cleanup(server.GracefulStop)
conn, err := grpc.Dial(
lis.Addr().String(),
grpc.WithTransportCredentials(insecure.NewCredentials()),
)
require.NoError(t, err)
t.Cleanup(func() { conn.Close() })
return streamingv1.NewStreamingServiceClient(conn)
}
func TestUnary_HappyPath(t *testing.T) {
server := grpc.NewServer()
svc := &mockStreamingService{
getItemFn: func(ctx context.Context, req *streamingv1.ItemRequest) (*streamingv1.ItemResponse, error) {
return &streamingv1.ItemResponse{
ItemId: req.ItemId,
Data: "item data here",
}, nil
},
}
streamingv1.RegisterStreamingServiceServer(server, svc)
client := setupTestClient(t, server)
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
resp, err := client.GetItem(ctx, &streamingv1.ItemRequest{ItemId: "item-123"})
require.NoError(t, err)
assert.Equal(t, "item-123", resp.ItemId)
assert.Equal(t, "item data here", resp.Data)
}
func TestUnary_NotFound(t *testing.T) {
server := grpc.NewServer()
svc := &mockStreamingService{
getItemFn: func(ctx context.Context, req *streamingv1.ItemRequest) (*streamingv1.ItemResponse, error) {
return nil, status.Errorf(codes.NotFound, "item %s not found", req.ItemId)
},
}
streamingv1.RegisterStreamingServiceServer(server, svc)
client := setupTestClient(t, server)
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
_, err := client.GetItem(ctx, &streamingv1.ItemRequest{ItemId: "nonexistent"})
require.Error(t, err)
st, ok := status.FromError(err)
require.True(t, ok)
assert.Equal(t, codes.NotFound, st.Code())
assert.Contains(t, st.Message(), "nonexistent")
}Testing Server-Streaming RPCs
Server streaming is where most teams hit problems. The test must handle multiple responses and verify stream termination:
func TestServerStreaming_ReceivesAllEvents(t *testing.T) {
expectedEvents := []*streamingv1.ItemEvent{
{EventType: "created", ItemId: "item-1", Data: "first item"},
{EventType: "updated", ItemId: "item-1", Data: "updated item"},
{EventType: "deleted", ItemId: "item-1"},
}
server := grpc.NewServer()
svc := &mockStreamingService{
watchItemsFn: func(req *streamingv1.WatchRequest, stream streamingv1.StreamingService_WatchItemsServer) error {
for _, event := range expectedEvents {
if err := stream.Send(event); err != nil {
return err
}
time.Sleep(10 * time.Millisecond) // simulate real-world timing
}
return nil // EOF — signals end of stream
},
}
streamingv1.RegisterStreamingServiceServer(server, svc)
client := setupTestClient(t, server)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
stream, err := client.WatchItems(ctx, &streamingv1.WatchRequest{Filter: "item-1"})
require.NoError(t, err)
var received []*streamingv1.ItemEvent
for {
event, err := stream.Recv()
if err == io.EOF {
break
}
require.NoError(t, err)
received = append(received, event)
}
require.Len(t, received, 3)
assert.Equal(t, "created", received[0].EventType)
assert.Equal(t, "updated", received[1].EventType)
assert.Equal(t, "deleted", received[2].EventType)
}
func TestServerStreaming_ClientCancellation(t *testing.T) {
// Test that server respects client cancellation
serverCancelled := make(chan struct{})
server := grpc.NewServer()
svc := &mockStreamingService{
watchItemsFn: func(req *streamingv1.WatchRequest, stream streamingv1.StreamingService_WatchItemsServer) error {
for i := 0; ; i++ {
select {
case <-stream.Context().Done():
close(serverCancelled)
return stream.Context().Err()
default:
event := &streamingv1.ItemEvent{
EventType: "heartbeat",
ItemId: fmt.Sprintf("item-%d", i),
}
if err := stream.Send(event); err != nil {
return err
}
time.Sleep(50 * time.Millisecond)
}
}
},
}
streamingv1.RegisterStreamingServiceServer(server, svc)
client := setupTestClient(t, server)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
stream, err := client.WatchItems(ctx, &streamingv1.WatchRequest{Filter: "*"})
require.NoError(t, err)
// Receive a few events then cancel
for i := 0; i < 3; i++ {
_, err := stream.Recv()
require.NoError(t, err)
}
cancel() // Cancel the client context
// Server should detect cancellation
select {
case <-serverCancelled:
// Good — server cleaned up
case <-time.After(2 * time.Second):
t.Fatal("Server did not respond to client cancellation within 2 seconds")
}
}
func TestServerStreaming_ErrorMidStream(t *testing.T) {
// Test that errors mid-stream are properly propagated
server := grpc.NewServer()
svc := &mockStreamingService{
watchItemsFn: func(req *streamingv1.WatchRequest, stream streamingv1.StreamingService_WatchItemsServer) error {
// Send one good event
if err := stream.Send(&streamingv1.ItemEvent{EventType: "created", ItemId: "item-1"}); err != nil {
return err
}
// Then return an error
return status.Errorf(codes.Internal, "database connection lost")
},
}
streamingv1.RegisterStreamingServiceServer(server, svc)
client := setupTestClient(t, server)
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
stream, err := client.WatchItems(ctx, &streamingv1.WatchRequest{Filter: "*"})
require.NoError(t, err)
// First Recv succeeds
event, err := stream.Recv()
require.NoError(t, err)
assert.Equal(t, "created", event.EventType)
// Second Recv should return the error
_, err = stream.Recv()
require.Error(t, err)
st, ok := status.FromError(err)
require.True(t, ok)
assert.Equal(t, codes.Internal, st.Code())
assert.Contains(t, st.Message(), "database connection lost")
}Testing Client-Streaming RPCs
Client streaming tests focus on correct aggregation behavior and handling of partial failures:
func TestClientStreaming_BatchUpload_Success(t *testing.T) {
server := grpc.NewServer()
svc := &mockStreamingService{
batchUploadFn: func(stream streamingv1.StreamingService_BatchUploadServer) error {
var uploaded int32
for {
req, err := stream.Recv()
if err == io.EOF {
return stream.SendAndClose(&streamingv1.BatchResult{
Uploaded: uploaded,
Failed: 0,
})
}
if err != nil {
return err
}
// Process each upload
_ = req.Content
uploaded++
}
},
}
streamingv1.RegisterStreamingServiceServer(server, svc)
client := setupTestClient(t, server)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
stream, err := client.BatchUpload(ctx)
require.NoError(t, err)
// Send multiple requests
files := []struct {
name string
content []byte
}{
{"file1.txt", []byte("content 1")},
{"file2.txt", []byte("content 2")},
{"file3.txt", []byte("content 3")},
}
for _, f := range files {
err := stream.Send(&streamingv1.UploadRequest{
Filename: f.name,
Content: f.content,
})
require.NoError(t, err)
}
result, err := stream.CloseAndRecv()
require.NoError(t, err)
assert.Equal(t, int32(3), result.Uploaded)
assert.Equal(t, int32(0), result.Failed)
assert.Empty(t, result.Errors)
}
func TestClientStreaming_PartialFailure(t *testing.T) {
server := grpc.NewServer()
svc := &mockStreamingService{
batchUploadFn: func(stream streamingv1.StreamingService_BatchUploadServer) error {
var uploaded, failed int32
var errors []string
for {
req, err := stream.Recv()
if err == io.EOF {
return stream.SendAndClose(&streamingv1.BatchResult{
Uploaded: uploaded,
Failed: failed,
Errors: errors,
})
}
if err != nil {
return err
}
// Simulate some files failing
if strings.HasSuffix(req.Filename, ".exe") {
failed++
errors = append(errors, fmt.Sprintf("%s: forbidden file type", req.Filename))
} else {
uploaded++
}
}
},
}
streamingv1.RegisterStreamingServiceServer(server, svc)
client := setupTestClient(t, server)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
stream, err := client.BatchUpload(ctx)
require.NoError(t, err)
err = stream.Send(&streamingv1.UploadRequest{Filename: "doc.pdf", Content: []byte("pdf content")})
require.NoError(t, err)
err = stream.Send(&streamingv1.UploadRequest{Filename: "malware.exe", Content: []byte("bad content")})
require.NoError(t, err)
err = stream.Send(&streamingv1.UploadRequest{Filename: "report.csv", Content: []byte("csv content")})
require.NoError(t, err)
result, err := stream.CloseAndRecv()
require.NoError(t, err)
assert.Equal(t, int32(2), result.Uploaded)
assert.Equal(t, int32(1), result.Failed)
assert.Len(t, result.Errors, 1)
assert.Contains(t, result.Errors[0], "malware.exe")
}Testing Bidirectional Streaming RPCs
Bidirectional streaming is the hardest to test correctly. Both sides send and receive independently:
func TestBidirectional_ChatExchange(t *testing.T) {
server := grpc.NewServer()
svc := &mockStreamingService{
chatFn: func(stream streamingv1.StreamingService_ChatServer) error {
for {
msg, err := stream.Recv()
if err == io.EOF {
return nil
}
if err != nil {
return err
}
// Echo back with a server prefix
reply := &streamingv1.ChatMessage{
Sender: "server",
Content: "echo: " + msg.Content,
Timestamp: time.Now().UnixMilli(),
}
if err := stream.Send(reply); err != nil {
return err
}
}
},
}
streamingv1.RegisterStreamingServiceServer(server, svc)
client := setupTestClient(t, server)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
stream, err := client.Chat(ctx)
require.NoError(t, err)
messages := []string{"hello", "world", "test"}
// Use goroutine for receiving since send/recv are independent
received := make(chan *streamingv1.ChatMessage, len(messages))
recvErr := make(chan error, 1)
go func() {
for {
msg, err := stream.Recv()
if err == io.EOF {
close(received)
return
}
if err != nil {
recvErr <- err
return
}
received <- msg
}
}()
// Send messages
for _, content := range messages {
err := stream.Send(&streamingv1.ChatMessage{
Sender: "client",
Content: content,
Timestamp: time.Now().UnixMilli(),
})
require.NoError(t, err)
}
// Close the client send side
err = stream.CloseSend()
require.NoError(t, err)
// Collect all received messages
var replies []*streamingv1.ChatMessage
for msg := range received {
replies = append(replies, msg)
}
select {
case err := <-recvErr:
t.Fatalf("Receive error: %v", err)
default:
}
require.Len(t, replies, 3)
assert.Equal(t, "echo: hello", replies[0].Content)
assert.Equal(t, "echo: world", replies[1].Content)
assert.Equal(t, "echo: test", replies[2].Content)
}
func TestBidirectional_ConcurrentSendReceive(t *testing.T) {
// Test that client can send and receive simultaneously
var serverReceived int32
var serverSent int32
server := grpc.NewServer()
svc := &mockStreamingService{
chatFn: func(stream streamingv1.StreamingService_ChatServer) error {
// Receive and send in separate goroutines to test concurrency
sendCh := make(chan struct{}, 10)
// Receive goroutine
go func() {
for {
if _, err := stream.Recv(); err != nil {
return
}
atomic.AddInt32(&serverReceived, 1)
sendCh <- struct{}{}
}
}()
// Send goroutine
for range sendCh {
msg := &streamingv1.ChatMessage{
Sender: "server",
Content: "ack",
}
if err := stream.Send(msg); err != nil {
return err
}
atomic.AddInt32(&serverSent, 1)
if atomic.LoadInt32(&serverSent) >= 5 {
return nil
}
}
return nil
},
}
streamingv1.RegisterStreamingServiceServer(server, svc)
client := setupTestClient(t, server)
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
stream, err := client.Chat(ctx)
require.NoError(t, err)
// Send 5 messages concurrently while receiving
var clientReceived int32
recvDone := make(chan struct{})
go func() {
defer close(recvDone)
for {
_, err := stream.Recv()
if err != nil {
return
}
atomic.AddInt32(&clientReceived, 1)
}
}()
for i := 0; i < 5; i++ {
err := stream.Send(&streamingv1.ChatMessage{
Sender: "client",
Content: fmt.Sprintf("message %d", i),
})
require.NoError(t, err)
time.Sleep(10 * time.Millisecond)
}
err = stream.CloseSend()
require.NoError(t, err)
<-recvDone
assert.Equal(t, int32(5), atomic.LoadInt32(&serverReceived))
assert.Equal(t, int32(5), atomic.LoadInt32(&clientReceived))
}Testing Stream Timeout and Backpressure
func TestServerStreaming_SlowConsumer(t *testing.T) {
// Test behavior when the client consumes responses slowly
server := grpc.NewServer()
svc := &mockStreamingService{
watchItemsFn: func(req *streamingv1.WatchRequest, stream streamingv1.StreamingService_WatchItemsServer) error {
for i := 0; i < 100; i++ {
event := &streamingv1.ItemEvent{
EventType: "update",
ItemId: fmt.Sprintf("item-%d", i),
}
if err := stream.Send(event); err != nil {
// Client disconnected or context cancelled — this is expected
return nil
}
}
return nil
},
}
streamingv1.RegisterStreamingServiceServer(server, svc)
client := setupTestClient(t, server)
// Short timeout — client can't consume all 100 events
ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
defer cancel()
stream, err := client.WatchItems(ctx, &streamingv1.WatchRequest{Filter: "*"})
require.NoError(t, err)
var count int
for {
_, err := stream.Recv()
if err != nil {
// Either EOF or context deadline exceeded — both acceptable
break
}
time.Sleep(20 * time.Millisecond) // Slow consumer
count++
}
// We should have received some but not all events
assert.Greater(t, count, 0)
assert.Less(t, count, 100)
}Key Testing Patterns Summary
Unary:
- Test happy path + error codes
- Verify request validation
- Test with missing/zero-value fields
Server streaming:
- Verify all items received in order
- Test client cancellation (server must clean up)
- Test error propagation mid-stream
- Test slow consumer behavior
Client streaming:
- Test full success path
- Test partial failures (some items fail, stream continues)
- Test server-side error causing stream abort
Bidirectional:
- Use goroutines for concurrent send/receive
- Test that
CloseSendcorrectly terminates the send side - Test ordering guarantees (if any)
- Test concurrent message handling
The most common mistake is testing streaming synchronously when the protocol is inherently concurrent. Using sync.WaitGroup or channels in tests makes them reliable across different load conditions.