Testing gRPC Streaming: Unary, Server-Stream, Client-Stream, Bidirectional
gRPC has four RPC types, not one. Most teams only test unary RPCs thoroughly and treat the streaming variants as second-class citizens. That's a mistake — streaming RPCs have unique failure modes around backpressure, partial delivery, stream cancellation, and reconnection that don't exist in unary calls.
This guide covers testing all four patterns: unary, server streaming, client streaming, and bidirectional streaming, with a focus on the edge cases that matter.
The Four Patterns
service DataService {
// Unary: one request, one response
rpc GetRecord (GetRecordRequest) returns (Record);
// Server streaming: one request, stream of responses
rpc ListRecords (ListRecordsRequest) returns (stream Record);
// Client streaming: stream of requests, one response
rpc BatchCreate (stream CreateRecordRequest) returns (BatchResult);
// Bidirectional streaming: stream of requests, stream of responses
rpc Process (stream ProcessRequest) returns (stream ProcessResult);
}Testing Unary RPCs
Unary is the simplest and most familiar pattern. The key things to test beyond the happy path:
func TestGetRecord_HappyPath(t *testing.T) {
client := newTestClient(t, &DataServiceImpl{store: &FakeStore{
records: map[string]*Record{"rec-1": {Id: "rec-1", Data: "hello"}},
}})
resp, err := client.GetRecord(context.Background(), &pb.GetRecordRequest{Id: "rec-1"})
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if resp.Data != "hello" {
t.Errorf("got %q, want %q", resp.Data, "hello")
}
}
func TestGetRecord_ContextCancellation(t *testing.T) {
// Simulate a slow store
slowStore := &SlowStore{delay: 500 * time.Millisecond}
client := newTestClient(t, &DataServiceImpl{store: slowStore})
ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
defer cancel()
_, err := client.GetRecord(ctx, &pb.GetRecordRequest{Id: "rec-1"})
if status.Code(err) != codes.DeadlineExceeded {
t.Errorf("got %v, want DeadlineExceeded", status.Code(err))
}
}Testing Server Streaming
Server streaming sends multiple messages to the client in response to a single request. Test the full sequence of messages, not just the first one.
Go: Testing the Full Stream
func TestListRecords_FullStream(t *testing.T) {
records := []*Record{
{Id: "rec-1", Data: "a"},
{Id: "rec-2", Data: "b"},
{Id: "rec-3", Data: "c"},
}
client := newTestClient(t, &DataServiceImpl{
store: &FakeStore{allRecords: records},
})
stream, err := client.ListRecords(context.Background(), &pb.ListRecordsRequest{})
if err != nil {
t.Fatalf("failed to start stream: %v", err)
}
var received []*pb.Record
for {
rec, err := stream.Recv()
if err == io.EOF {
break
}
if err != nil {
t.Fatalf("stream recv error: %v", err)
}
received = append(received, rec)
}
if len(received) != len(records) {
t.Errorf("got %d records, want %d", len(received), len(records))
}
for i, rec := range received {
if rec.Id != records[i].Id {
t.Errorf("record %d: got id %q, want %q", i, rec.Id, records[i].Id)
}
}
}Testing the Server Side of Streaming
Test the StreamObserver/stream send loop directly:
type FakeServerStream struct {
grpc.ServerStream
sent []*pb.Record
ctx context.Context
sendErr error
}
func (f *FakeServerStream) Send(rec *pb.Record) error {
if f.sendErr != nil {
return f.sendErr
}
f.sent = append(f.sent, rec)
return nil
}
func (f *FakeServerStream) Context() context.Context {
return f.ctx
}
func TestListRecords_ServerSendsAllRecords(t *testing.T) {
svc := &DataServiceImpl{store: &FakeStore{
allRecords: []*Record{{Id: "rec-1"}, {Id: "rec-2"}, {Id: "rec-3"}},
}}
stream := &FakeServerStream{ctx: context.Background()}
err := svc.ListRecords(&pb.ListRecordsRequest{}, stream)
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
if len(stream.sent) != 3 {
t.Errorf("expected 3 records sent, got %d", len(stream.sent))
}
}
func TestListRecords_SendError_StopsStream(t *testing.T) {
svc := &DataServiceImpl{store: &FakeStore{
allRecords: []*Record{{Id: "rec-1"}, {Id: "rec-2"}, {Id: "rec-3"}},
}}
stream := &FakeServerStream{
ctx: context.Background(),
sendErr: status.Error(codes.Unavailable, "client disconnected"),
}
err := svc.ListRecords(&pb.ListRecordsRequest{}, stream)
// The service should stop and return the send error (or a wrapped version)
if err == nil {
t.Error("expected error when send fails, got nil")
}
}Testing Backpressure
Backpressure in gRPC server streaming is controlled by the flow control window. If the client isn't reading fast enough, Send() blocks. Test that your service handles a slow client without leaking resources:
func TestListRecords_SlowClient_NoResourceLeak(t *testing.T) {
// Create a stream that introduces artificial delay on receive
client := newTestClient(t, &DataServiceImpl{
store: &FakeStore{allRecords: generateRecords(1000)},
})
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
stream, err := client.ListRecords(ctx, &pb.ListRecordsRequest{})
if err != nil {
t.Fatal(err)
}
// Read slowly — one record per 5ms, total 1000 records = 5s, but timeout is 2s
count := 0
for {
_, err := stream.Recv()
if err == io.EOF {
break
}
if err != nil {
// Expect DeadlineExceeded — this is the correct behavior
if status.Code(err) == codes.DeadlineExceeded || err == context.DeadlineExceeded {
break
}
t.Fatalf("unexpected error: %v", err)
}
count++
time.Sleep(5 * time.Millisecond)
}
// After cancellation, the server should stop sending
// Verify by checking that the server-side goroutine has exited
// (In practice, use a WaitGroup or channel in your fake store)
t.Logf("received %d records before timeout", count)
}Testing Client Streaming
Client streaming receives multiple messages from the client and produces one response. Test that the server correctly aggregates all messages.
Go: Client Streaming Test
func TestBatchCreate_AllMessagesProcessed(t *testing.T) {
store := &FakeStore{records: map[string]*Record{}}
client := newTestClient(t, &DataServiceImpl{store: store})
stream, err := client.BatchCreate(context.Background())
if err != nil {
t.Fatalf("failed to start stream: %v", err)
}
requests := []*pb.CreateRecordRequest{
{Data: "record-a"},
{Data: "record-b"},
{Data: "record-c"},
}
for _, req := range requests {
if err := stream.Send(req); err != nil {
t.Fatalf("send failed: %v", err)
}
}
result, err := stream.CloseAndRecv()
if err != nil {
t.Fatalf("CloseAndRecv failed: %v", err)
}
if result.Created != int32(len(requests)) {
t.Errorf("created %d records, want %d", result.Created, len(requests))
}
}Testing the Server Side of Client Streaming
type FakeClientStream struct {
grpc.ServerStream
requests []*pb.CreateRecordRequest
pos int
ctx context.Context
}
func (f *FakeClientStream) Recv() (*pb.CreateRecordRequest, error) {
if f.pos >= len(f.requests) {
return nil, io.EOF
}
req := f.requests[f.pos]
f.pos++
return req, nil
}
func (f *FakeClientStream) Context() context.Context { return f.ctx }
func (f *FakeClientStream) SendAndClose(result *pb.BatchResult) error { return nil }
func TestBatchCreate_PartialFailure(t *testing.T) {
svc := &DataServiceImpl{store: &PartialFailStore{failAfter: 2}}
stream := &FakeClientStream{
ctx: context.Background(),
requests: []*pb.CreateRecordRequest{
{Data: "record-a"},
{Data: "record-b"},
{Data: "record-c"}, // this one will fail
},
}
// If your service returns partial results, verify count and error
err := svc.BatchCreate(stream)
// Assertion depends on your partial failure contract
if err != nil {
if status.Code(err) != codes.Internal {
t.Errorf("expected Internal error, got %v", status.Code(err))
}
}
}Testing Send After Stream Close
A client sending after CloseAndRecv() or after the server has responded is an error condition worth testing:
func TestBatchCreate_SendAfterClose(t *testing.T) {
client := newTestClient(t, &DataServiceImpl{store: &FakeStore{}})
stream, _ := client.BatchCreate(context.Background())
stream.Send(&pb.CreateRecordRequest{Data: "record-a"})
stream.CloseAndRecv()
// Sending after close should return an error
err := stream.Send(&pb.CreateRecordRequest{Data: "late-record"})
if err == nil {
t.Error("expected error when sending after CloseAndRecv, got nil")
}
}Testing Bidirectional Streaming
Bidirectional streaming is the most complex pattern. The client and server both send and receive independently. The failure modes are numerous.
Go: Basic Bidirectional Test
func TestProcess_EchoScenario(t *testing.T) {
client := newTestClient(t, &DataServiceImpl{})
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
stream, err := client.Process(ctx)
if err != nil {
t.Fatalf("failed to start stream: %v", err)
}
// Send messages and receive responses concurrently
var wg sync.WaitGroup
var received []*pb.ProcessResult
var recvErr error
var mu sync.Mutex
wg.Add(1)
go func() {
defer wg.Done()
for {
result, err := stream.Recv()
if err == io.EOF {
return
}
if err != nil {
mu.Lock()
recvErr = err
mu.Unlock()
return
}
mu.Lock()
received = append(received, result)
mu.Unlock()
}
}()
requests := []string{"input-a", "input-b", "input-c"}
for _, data := range requests {
if err := stream.Send(&pb.ProcessRequest{Data: data}); err != nil {
t.Fatalf("send failed: %v", err)
}
}
stream.CloseSend()
wg.Wait()
mu.Lock()
defer mu.Unlock()
if recvErr != nil {
t.Fatalf("recv error: %v", recvErr)
}
if len(received) != len(requests) {
t.Errorf("got %d results, want %d", len(received), len(requests))
}
}Testing Error Handling Mid-Stream
When the server sends an error in the middle of a bidirectional stream, the client should receive it on Recv(). Test this explicitly:
func TestProcess_ServerErrorMidStream(t *testing.T) {
// Server that errors after 2 responses
svc := &DataServiceImpl{
processFunc: func(stream pb.DataService_ProcessServer) error {
for i := 0; i < 2; i++ {
req, err := stream.Recv()
if err != nil {
return err
}
if err := stream.Send(&pb.ProcessResult{Output: req.Data}); err != nil {
return err
}
}
return status.Error(codes.Internal, "processing limit reached")
},
}
client := newTestClient(t, svc)
stream, _ := client.Process(context.Background())
// Send more than the server will process
for i := 0; i < 5; i++ {
stream.Send(&pb.ProcessRequest{Data: fmt.Sprintf("input-%d", i)})
}
// Receive until error
var results []*pb.ProcessResult
for {
result, err := stream.Recv()
if err != nil {
if status.Code(err) != codes.Internal {
t.Errorf("got status %v, want Internal", status.Code(err))
}
break
}
results = append(results, result)
}
if len(results) != 2 {
t.Errorf("got %d results before error, want 2", len(results))
}
}Testing Timeout Mid-Stream
func TestProcess_TimeoutMidStream(t *testing.T) {
svc := &DataServiceImpl{
processFunc: func(stream pb.DataService_ProcessServer) error {
for {
req, err := stream.Recv()
if err != nil {
return err
}
// Artificially slow processing
time.Sleep(200 * time.Millisecond)
if err := stream.Send(&pb.ProcessResult{Output: req.Data}); err != nil {
return err
}
}
},
}
client := newTestClient(t, svc)
ctx, cancel := context.WithTimeout(context.Background(), 300*time.Millisecond)
defer cancel()
stream, _ := client.Process(ctx)
// First response should succeed (200ms < 300ms timeout)
stream.Send(&pb.ProcessRequest{Data: "first"})
first, err := stream.Recv()
if err != nil {
t.Fatalf("expected first response, got error: %v", err)
}
if first.Output != "first" {
t.Errorf("wrong first output: %q", first.Output)
}
// Second send (after 200ms already elapsed, next response at 400ms > timeout)
stream.Send(&pb.ProcessRequest{Data: "second"})
_, err = stream.Recv()
if status.Code(err) != codes.DeadlineExceeded {
t.Errorf("got %v, want DeadlineExceeded", status.Code(err))
}
}Testing Reconnection Logic
gRPC client-side reconnection is handled by the channel, but your application logic may have reconnection code for streaming RPCs. Test that reconnection:
- Resumes from the correct position (if your protocol supports it)
- Doesn't duplicate messages
- Handles the case where the server is unavailable
func TestStreamClient_ReconnectsOnDisconnect(t *testing.T) {
var callCount atomic.Int32
svc := &DataServiceImpl{
listFunc: func(req *pb.ListRecordsRequest, stream pb.DataService_ListRecordsServer) error {
call := callCount.Add(1)
if call == 1 {
// First call: send one record then drop the connection
stream.Send(&pb.Record{Id: "rec-1"})
return status.Error(codes.Unavailable, "server restarting")
}
// Second call: send remaining records
stream.Send(&pb.Record{Id: "rec-2"})
stream.Send(&pb.Record{Id: "rec-3"})
return nil
},
}
client := newTestClient(t, svc)
// Your stream consumer with reconnection logic
consumer := &StreamConsumer{
client: client,
maxRetries: 3,
backoff: 10 * time.Millisecond,
}
records, err := consumer.ConsumeAll(context.Background(), &pb.ListRecordsRequest{})
if err != nil {
t.Fatalf("unexpected error: %v", err)
}
// Verify no duplicates and all records received
seen := map[string]bool{}
for _, rec := range records {
if seen[rec.Id] {
t.Errorf("duplicate record: %q", rec.Id)
}
seen[rec.Id] = true
}
if callCount.Load() != 2 {
t.Errorf("expected 2 calls (1 failure + 1 retry), got %d", callCount.Load())
}
}Structuring Streaming Tests
Streaming tests are slower and harder to debug than unary tests. Structure them to fail fast and provide clear diagnostics:
// Helper that receives all messages from a server stream with a timeout
func drainStream[T proto.Message](t *testing.T, stream interface{ Recv() (T, error) }, timeout time.Duration) []T {
t.Helper()
done := make(chan struct{})
var messages []T
var recvErr error
go func() {
defer close(done)
for {
msg, err := stream.Recv()
if err == io.EOF {
return
}
if err != nil {
recvErr = err
return
}
messages = append(messages, msg)
}
}()
select {
case <-done:
case <-time.After(timeout):
t.Fatalf("stream did not complete within %v", timeout)
}
if recvErr != nil {
t.Fatalf("stream recv error: %v", recvErr)
}
return messages
}Use this helper to keep streaming tests readable:
func TestListRecords_Returns100Records(t *testing.T) {
client := newTestClient(t, &DataServiceImpl{
store: &FakeStore{allRecords: generateRecords(100)},
})
stream, err := client.ListRecords(context.Background(), &pb.ListRecordsRequest{})
if err != nil {
t.Fatal(err)
}
records := drainStream(t, stream, 5*time.Second)
if len(records) != 100 {
t.Errorf("got %d records, want 100", len(records))
}
}Summary: What to Test Per Pattern
| Pattern | Key test scenarios |
|---|---|
| Unary | Happy path, not found, invalid input, deadline exceeded |
| Server streaming | All messages received, send error stops stream, slow client behavior, context cancellation |
| Client streaming | All sends processed, partial failure handling, send after close |
| Bidirectional | Concurrent send/recv, server error mid-stream, timeout mid-stream, reconnection |
The streaming patterns that teams test least are the ones that cause the most production incidents. A bidirectional stream that leaks a goroutine on disconnect, or a server streaming handler that holds a database cursor open when the client disconnects, are bugs that only appear under realistic conditions — and only if you write the tests.
HelpMeTest can monitor your gRPC streaming endpoints in production, detecting silent failures like streams that start but never deliver all expected messages. If you're running event-driven services over gRPC streams, that's the observability layer worth having.