Integration Grpc Extension

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.

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.

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

• Integration: Amazon S3 Extension
• Integration: Amazon DynamoDB Extension
• Integration: SQS Extension
• Integration: MongoDB Extension