grpc-testing

name	grpc-testing
description	gRPC integration testing for ASP.NET Core — test infrastructure, fixtures, patterns for all RPC types, code coverage with coverlet, and mocking strategies. Use when writing or improving gRPC tests.

gRPC Integration Testing

Test Project Setup

Package References

<PackageReference Include="Microsoft.AspNetCore.Mvc.Testing" Version="*" />
<PackageReference Include="Grpc.Net.Client" Version="*" />
<PackageReference Include="Grpc.Tools" Version="*" PrivateAssets="All" />
<PackageReference Include="Google.Protobuf" Version="*" />
<PackageReference Include="coverlet.collector" Version="*" PrivateAssets="All" />
<PackageReference Include="xunit" Version="*" />
<PackageReference Include="xunit.runner.visualstudio" Version="*" PrivateAssets="All" />

Proto References

Reference the same proto files as the server, but with client generation:

<Protobuf Include="..\Server\Protos\*.proto" GrpcServices="Client" Link="Protos\%(Filename).proto" />

---

Test Fixture

WebApplicationFactory + GrpcChannel

public class GrpcTestFixture<TProgram> : IDisposable where TProgram : class
{
    private readonly WebApplicationFactory<TProgram> _factory;
    public GrpcChannel Channel { get; }

    public GrpcTestFixture()
    {
        _factory = new WebApplicationFactory<TProgram>();
        var client = _factory.CreateDefaultClient(new ResponseVersionHandler());
        Channel = GrpcChannel.ForAddress(client.BaseAddress!, new GrpcChannelOptions
        {
            HttpClient = client
        });
    }

    public void Dispose()
    {
        Channel.Dispose();
        _factory.Dispose();
    }
}

// Force HTTP/2 for test client
public class ResponseVersionHandler : DelegatingHandler
{
    protected override async Task<HttpResponseMessage> SendAsync(
        HttpRequestMessage request, CancellationToken ct)
    {
        request.Version = new Version(2, 0);
        var response = await base.SendAsync(request, ct);
        response.Version = request.Version;
        return response;
    }
}

With DI Overrides (Mocking)

public class GrpcTestFixture<TProgram> : IDisposable where TProgram : class
{
    private readonly WebApplicationFactory<TProgram> _factory;
    public GrpcChannel Channel { get; }

    public GrpcTestFixture(Action<IServiceCollection>? configureServices = null)
    {
        _factory = new WebApplicationFactory<TProgram>().WithWebHostBuilder(builder =>
        {
            if (configureServices is not null)
                builder.ConfigureServices(configureServices);
        });
        var client = _factory.CreateDefaultClient(new ResponseVersionHandler());
        Channel = GrpcChannel.ForAddress(client.BaseAddress!, new GrpcChannelOptions
        {
            HttpClient = client
        });
    }

    public void Dispose()
    {
        Channel.Dispose();
        _factory.Dispose();
    }
}

---

Test Patterns by RPC Type

Unary RPC

[Fact]
public async Task GetUser_ValidId_ReturnsUser()
{
    var client = new UserService.UserServiceClient(Channel);
    var response = await client.GetUserAsync(new GetUserRequest { UserId = "123" });
    Assert.Equal("123", response.User.Id);
}

[Fact]
public async Task GetUser_InvalidId_ThrowsNotFound()
{
    var client = new UserService.UserServiceClient(Channel);
    var ex = await Assert.ThrowsAsync<RpcException>(
        () => client.GetUserAsync(new GetUserRequest { UserId = "nonexistent" }));
    Assert.Equal(StatusCode.NotFound, ex.StatusCode);
}

Server Streaming

[Fact]
public async Task ListUsers_ReturnsAllUsers()
{
    var client = new UserService.UserServiceClient(Channel);
    var users = new List<UserResponse>();

    using var call = client.ListUsers(new ListUsersRequest { PageSize = 10 });
    await foreach (var user in call.ResponseStream.ReadAllAsync())
    {
        users.Add(user);
    }

    Assert.NotEmpty(users);
    Assert.True(users.Count <= 10);
}

[Fact]
public async Task ListUsers_Cancellation_StopsStream()
{
    var client = new UserService.UserServiceClient(Channel);
    using var cts = new CancellationTokenSource();
    var count = 0;

    using var call = client.ListUsers(new ListUsersRequest());
    await Assert.ThrowsAsync<RpcException>(async () =>
    {
        await foreach (var user in call.ResponseStream.ReadAllAsync(cts.Token))
        {
            count++;
            if (count >= 2) cts.Cancel();
        }
    });
}

Client Streaming

[Fact]
public async Task UploadData_SendsChunks_ReturnsTotal()
{
    var client = new DataService.DataServiceClient(Channel);
    using var call = client.UploadData();

    for (int i = 0; i < 5; i++)
    {
        await call.RequestStream.WriteAsync(new DataChunk { Data = ByteString.CopyFromUtf8($"chunk{i}") });
    }
    await call.RequestStream.CompleteAsync();

    var result = await call;
    Assert.Equal(5, result.ChunksReceived);
}

Bidirectional Streaming

[Fact]
public async Task Chat_EchosMessages()
{
    var client = new ChatService.ChatServiceClient(Channel);
    using var call = client.Chat();
    var received = new List<string>();

    var readTask = Task.Run(async () =>
    {
        await foreach (var msg in call.ResponseStream.ReadAllAsync())
        {
            received.Add(msg.Text);
        }
    });

    await call.RequestStream.WriteAsync(new ChatMessage { Text = "Hello" });
    await call.RequestStream.WriteAsync(new ChatMessage { Text = "World" });
    await call.RequestStream.CompleteAsync();

    await readTask;
    Assert.Equal(2, received.Count);
}

---

Deadline & Cancellation Tests

[Fact]
public async Task SlowMethod_WithTightDeadline_ThrowsDeadlineExceeded()
{
    var client = new MyService.MyServiceClient(Channel);
    var deadline = DateTime.UtcNow.AddMilliseconds(1);

    var ex = await Assert.ThrowsAsync<RpcException>(
        () => client.SlowMethodAsync(new Request(), deadline: deadline));

    Assert.Equal(StatusCode.DeadlineExceeded, ex.StatusCode);
}

[Fact]
public async Task Method_WithCancelledToken_ThrowsCancelled()
{
    var client = new MyService.MyServiceClient(Channel);
    using var cts = new CancellationTokenSource();
    cts.Cancel();

    var ex = await Assert.ThrowsAsync<RpcException>(
        () => client.MyMethodAsync(new Request(), cancellationToken: cts.Token));

    Assert.Equal(StatusCode.Cancelled, ex.StatusCode);
}

---

Code Coverage

Collect Coverage

dotnet test --collect:"XPlat Code Coverage" --results-directory ./coverage

Generate Text Report

dotnet tool install -g dotnet-reportgenerator-globaltool
reportgenerator \
  -reports:./coverage/**/coverage.cobertura.xml \
  -targetdir:./coverage/report \
  -reporttypes:TextSummary
cat ./coverage/report/Summary.txt

Coverage Targets for gRPC Services

Metric	Target
Line coverage	80%+
Branch coverage	70%+
RPC method coverage	100% (every method has at least 1 test)
Error path coverage	Every RpcException throw site tested

Interpreting Cobertura XML

• <class> elements map to C# classes — focus on Services/*.cs
• line-rate = line coverage (0.0 to 1.0)
• branch-rate = branch coverage (0.0 to 1.0)
• Lines with hits="0" are untested — prioritize these

---

Mocking Strategies

Override DI Services

var fixture = new GrpcTestFixture<Program>(services =>
{
    services.AddSingleton<IUserRepository>(new FakeUserRepository());
});

Use NSubstitute or Moq

var mockRepo = Substitute.For<IUserRepository>();
mockRepo.GetAsync(Arg.Any<string>(), Arg.Any<CancellationToken>())
    .Returns(new User { Id = "123", Name = "Test" });

var fixture = new GrpcTestFixture<Program>(services =>
{
    services.AddSingleton(mockRepo);
});

---

Test Naming Convention

MethodName_Scenario_ExpectedResult

Examples:

• GetItem_ValidId_ReturnsItem
• GetItem_EmptyId_ThrowsInvalidArgument
• ListUsers_Cancellation_StopsStream
• UploadData_EmptyStream_ReturnsZeroChunks

---

Test Organization

File Structure — One Class per gRPC Pattern

Never put all tests in a single file. Split by gRPC pattern or feature:

Tests/
  {Service}UnaryTests.cs                  — Unary CRUD RPCs
  {Service}FieldMaskTests.cs              — FieldMask partial updates
  {Service}ServerStreamingTests.cs        — Server streaming RPCs
  {Service}ClientStreamingTests.cs        — Client streaming RPCs
  {Service}BidiStreamingTests.cs          — Bidirectional streaming RPCs
  {Service}DeadlineCancellationTests.cs   — Deadline and cancellation behavior

Use IClassFixture<T> — Not Manual Fixture Creation

xUnit's IClassFixture<T> ensures the fixture is created once per class, not per test. The fixture class must have exactly one public parameterless constructor.

// CORRECT
public class MyServiceUnaryTests(GrpcTestFixture<Program> fixture)
    : IClassFixture<GrpcTestFixture<Program>>
{
    private readonly MyService.MyServiceClient _client = new(fixture.Channel);
}

Required Coverage per Class

Class	Must Test
UnaryTests	Success path + every RpcException the RPC can throw
FieldMaskTests	Selective field update, bool toggle, multi-field mask
ServerStreamingTests	Full stream, filtered stream, empty stream
ClientStreamingTests	Multiple items, empty stream, invalid item skipping
BidiStreamingTests	Every oneof variant, not-found per variant, mixed, empty command
DeadlineCancellationTests	Expired deadline, cancelled token on unary + streaming + bidi