Testing gRPC Streaming: Unary, Server-Stream, Client-Stream, Bidirectional

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:

  1. Resumes from the correct position (if your protocol supports it)
  2. Doesn't duplicate messages
  3. 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.

Read more

Start now free