Skip to content

Integration Grpc Extension

Jump to bottom
Aryeh Citron edited this page Apr 26, 2026 · 17 revisions

Integration: gRPC Extension

Track gRPC client calls in your test diagrams using the TestTrackingDiagrams.Extensions.Grpc NuGet package. This extension intercepts all gRPC call types (unary, server-streaming, client-streaming, duplex-streaming) via the standard Grpc.Core.Interceptors.Interceptor API.

Using a shared library or abstraction layer? If your code doesn't use gRPC channels directly — e.g. it goes through a shared client library or custom abstraction — this extension won't be able to intercept the underlying calls. See Tracking Custom Dependencies for alternative approaches including RequestResponseLogger.LogPair() and TrackingProxy<T>.

Installation

dotnet add package TestTrackingDiagrams.Extensions.Grpc

Quick Start

What your production code looks like

Your production code creates gRPC clients normally — no tracking code here:

// Program.cs / Startup.cs — register gRPC clients via DI
services.AddSingleton(sp =>
{
    var channel = GrpcChannel.ForAddress("https://greeter-service:5001");
    return new Greeter.GreeterClient(channel);
});

// Or using the gRPC client factory:
services.AddGrpcClient<Greeter.GreeterClient>(o =>
{
    o.Address = new Uri("https://greeter-service:5001");
});
// GreetingService.cs — uses the client via DI (no tracking awareness)
public class GreetingService
{
    private readonly Greeter.GreeterClient _greeterClient;

    public GreetingService(Greeter.GreeterClient greeterClient)
    {
        _greeterClient = greeterClient;
    }

    public async Task<string> GetGreeting(string name)
    {
        var reply = await _greeterClient.SayHelloAsync(new HelloRequest { Name = name });
        return reply.Message;
    }
}

Adding tracking in your tests

In your test setup, replace the production gRPC client registration with a tracked version. The WithTestTracking extension wraps the channel with a GrpcTrackingInterceptor that records all gRPC calls for sequence diagrams:

// TestSetupHooks.cs or WebApplicationFactory setup
builder.ConfigureTestServices(services =>
{
    // Replace the production client with a tracked one
    services.AddSingleton(sp =>
    {
        var channel = GrpcChannel.ForAddress("https://localhost:5001");
        var invoker = channel.WithTestTracking(new GrpcTrackingOptions
        {
            ServiceName = "GreeterService",
            CallingServiceName = "MyApi",
            Verbosity = GrpcTrackingVerbosity.Detailed,
            CurrentTestInfoFetcher = () => (TestContext.CurrentTestName, TestContext.CurrentTestId)
        });
        return new Greeter.GreeterClient(invoker);
    });
});

Or use the interceptor directly if you prefer:

var interceptor = new GrpcTrackingInterceptor(new GrpcTrackingOptions
{
    ServiceName = "GreeterService",
    CallingServiceName = "MyApi",
    CurrentTestInfoFetcher = () => (TestContext.CurrentTestName, TestContext.CurrentTestId)
});

var channel = GrpcChannel.ForAddress("https://localhost:5001");
var invoker = channel.Intercept(interceptor);
var client = new Greeter.GreeterClient(invoker);

Key point: Your production code (controllers, services, etc.) stays unchanged. The only difference is how the gRPC client is constructed — tests wrap the channel with the tracking interceptor via DI replacement.

Tracking Incoming gRPC Calls (Test → SUT)

If your SUT exposes a gRPC service (i.e. the test calls the SUT via gRPC), you can get rich gRPC-aware diagrams for the incoming leg too — with protobuf message deserialization, operation classification, and grpc:// URIs. Without this, incoming gRPC calls would appear as raw HTTP/2 POST requests with binary bodies.

Use GrpcTrackingChannel.Create() to build a tracked CallInvoker from the test server's handler:

using TestTrackingDiagrams.Extensions.Grpc;

// In your test setup (e.g. constructor, [BeforeScenario], etc.)
var invoker = GrpcTrackingChannel.Create(
    factory.Server.CreateHandler(),
    factory.Server.BaseAddress,
    new GrpcTrackingOptions
    {
        ServiceName = "My API",
        CallingServiceName = "Test",
        Verbosity = GrpcTrackingVerbosity.Detailed,
        CurrentTestInfoFetcher = () =>
        {
            var test = TestContext.Current.Test;
            return test is not null
                ? (test.TestDisplayName, test.UniqueID)
                : ("Unknown", "unknown");
        }
    });

// Create your typed gRPC client from the tracked invoker
var client = new Greeter.GreeterClient(invoker);

If you need to dispose the underlying GrpcChannel cleanly (e.g. in [AfterScenario]), use CreateWithChannel:

var (invoker, channel) = GrpcTrackingChannel.CreateWithChannel(
    factory.Server.CreateHandler(),
    factory.Server.BaseAddress,
    new GrpcTrackingOptions
    {
        ServiceName = "My API",
        CallingServiceName = "Test",
        CurrentTestInfoFetcher = () => (TestContext.Current.Test!.TestDisplayName, TestContext.Current.Test!.UniqueID)
    });

var client = new Greeter.GreeterClient(invoker);

// Later, in cleanup:
channel.Dispose();

There's also an extension method on HttpMessageHandler for terser syntax:

var invoker = factory.Server.CreateHandler()
    .AsGrpcTrackingCallInvoker(factory.Server.BaseAddress, grpcOptions);

What you get vs raw HTTP tracking

Aspect Without gRPC extension With GrpcTrackingChannel.Create()
Label POST SayHello or StreamOrders (server-stream)
URI http://localhost/greet.Greeter/SayHello grpc:///greet.Greeter/SayHello
Request body Binary protobuf (unreadable) JSON-formatted protobuf fields
Response body Binary protobuf JSON-formatted protobuf fields
Operation type None UnaryCall, ServerStreamingCall, etc.
Status mapping HTTP/2 status gRPC StatusCode → HTTP mapping
Dependency colour HTTP (blue) gRPC (uses DependencyCategory: "gRPC")

Important: Do not also wrap the underlying HTTP handler with TestTrackingMessageHandler or CreateTestTrackingClient() for gRPC calls — this would produce duplicate diagram entries (one from the HTTP layer, one from the gRPC interceptor). Use GrpcTrackingChannel.Create() instead of, not in addition to, HTTP tracking for the gRPC test client.

Tip: If your test project makes both HTTP and gRPC calls to the SUT, use CreateTestTrackingClient() for the HTTP client and GrpcTrackingChannel.Create() for the gRPC client. They log to the same RequestResponseLogger and will appear together in the same diagram.

How It Works

GrpcTrackingInterceptor extends Grpc.Core.Interceptors.Interceptor, overriding all five call types:

Call Type Override Tracking
Async Unary AsyncUnaryCall Full request + response
Blocking Unary BlockingUnaryCall Full request + response
Server Streaming AsyncServerStreamingCall Request + call initiation
Client Streaming AsyncClientStreamingCall Call initiation + response
Duplex Streaming AsyncDuplexStreamingCall Call initiation + response

Streaming calls are tracked at the initiation level (not per-message) to keep diagrams clean.

Supported Operations

Method Type Enum Value
Unary GrpcOperation.UnaryCall
Server Streaming GrpcOperation.ServerStreamingCall
Client Streaming GrpcOperation.ClientStreamingCall
Duplex Streaming GrpcOperation.DuplexStreamingCall

Message Serialization

Request and response messages are serialized for diagram content:

  • Protobuf IMessage: Uses Google.Protobuf.JsonFormatter.Default.Format() for JSON output
  • Other types: Falls back to .ToString()
  • Summarised verbosity: Content omitted entirely

gRPC Status Code Mapping

gRPC status codes are mapped to HTTP status codes for consistent diagram logging:

gRPC Status HTTP Status
OK 200 OK
NotFound 404 Not Found
PermissionDenied 403 Forbidden
Unauthenticated 401 Unauthorized
InvalidArgument 400 Bad Request
DeadlineExceeded 408 Request Timeout
AlreadyExists 409 Conflict
ResourceExhausted 429 Too Many Requests
Unavailable 503 Service Unavailable
Unimplemented 501 Not Implemented
Cancelled 408 Request Timeout
Other 500 Internal Server Error

Verbosity Levels

GrpcTrackingVerbosity.Summarised

Minimal output:

  • Label: Method name only (e.g. SayHello)
  • URI: grpc:///ServiceName/
  • Content: Omitted
  • Headers: Omitted

GrpcTrackingVerbosity.Detailed

Balanced output:

  • Label: Method name with streaming annotation (e.g. SayHello, StreamMessages (server-stream))
  • URI: grpc:///ServiceName/MethodName
  • Content: Serialized protobuf messages
  • Headers: Omitted

GrpcTrackingVerbosity.Raw

Full output:

  • Label: /package.Service/Method [UnaryCall]
  • URI: grpc:///package.Service/Method
  • Content: Serialized protobuf messages
  • Headers: Included (non-binary metadata entries)

Configuration Options

new GrpcTrackingOptions
{
    // Display name in diagrams (default: "GrpcService")
    ServiceName = "GreeterService",

    // Calling service name in diagrams (default: "Caller")
    CallingServiceName = "MyApi",

    // Verbosity level (default: Detailed)
    Verbosity = GrpcTrackingVerbosity.Detailed,

    // Required: provides test context
    CurrentTestInfoFetcher = () => (testName, testId),

    // Use proto service name instead of ServiceName (default: false)
    UseProtoServiceNameInDiagram = false
}

GrpcTrackingOptions

Property Type Default Description
ServiceName string "GrpcService" Display name in diagrams for the gRPC service
CallingServiceName string "Caller" Calling service name in diagrams
Verbosity GrpcTrackingVerbosity Detailed Verbosity level (Raw, Detailed, Summarised)
CurrentTestInfoFetcher Func<(string Name, string Id)>? null Required: provides test context
CurrentStepTypeFetcher Func<string?>? null Optional — returns the current BDD step type (Given/When/Then)

v2.23.0+ Dual-Resolution: GrpcTrackingInterceptor accepts an optional IHttpContextAccessor? httpContextAccessor constructor parameter for resolving test identity from HTTP request headers when running inside the SUT's request pipeline. See HTTP Tracking Setup#Dual-Resolution Test Identity (v2.23.0+) for details.

| UseProtoServiceNameInDiagram | bool | false | Use proto service name instead of ServiceName | | SetupVerbosity | GrpcTrackingVerbosity? | null | Verbosity override for the Setup phase. See Phase-Aware Tracking | | ActionVerbosity | GrpcTrackingVerbosity? | null | Verbosity override for the Action phase. See Phase-Aware Tracking | | TrackDuringSetup | bool | true | When false, tracking is suppressed during Setup. See Phase-Aware Tracking | | TrackDuringAction | bool | true | When false, tracking is suppressed during Action. See Phase-Aware Tracking |

UseProtoServiceNameInDiagram

When true, the proto service name from the method definition (e.g. greet.Greeter) is used as the service name in diagrams instead of the configured ServiceName. Useful when tracking multiple gRPC services through a single interceptor.

ITrackingComponent

GrpcTrackingInterceptor implements ITrackingComponent and auto-registers with TrackingComponentRegistry:

  • ComponentName: "GrpcTrackingInterceptor ({ServiceName})"
  • WasInvoked: true after first call
  • InvocationCount: Total calls processed (all call types)

URI Scheme

Verbosity Format Example
Summarised grpc:///ServiceName/ grpc:///greet.Greeter/
Detailed grpc:///ServiceName/MethodName grpc:///greet.Greeter/SayHello
Raw grpc:///FullMethodPath grpc:////greet.Greeter/SayHello

See Also

Home

Demo

Getting Started

Common Tasks

Integration Guides

Extensions

Configuration

Features

Reference

Clone this wiki locally