gRPC Streaming Testing Patterns: Unary, Server-Side, and Bidirectional

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 CloseSend correctly 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.

Read more

Start now free