Mock gRPC client in tests

Note

This isn't the latest version of this article. For the current release, see the .NET 8 version of this article.

Warning

This version of ASP.NET Core is no longer supported. For more information, see .NET and .NET Core Support Policy. For the current release, see the .NET 8 version of this article.

Important

This information relates to a pre-release product that may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

For the current release, see the .NET 8 version of this article.

By: James Newton-King

Testing is an important aspect of building stable and maintainable software. Part of writing high-quality tests is removing external dependencies. This article discusses using mock gRPC clients in tests to remove gRPC calls to external servers.

Example testable client app

To demonstrate client app tests, review the following type in the sample app.

View or download sample code (how to download)

The Worker is a BackgroundService that makes calls to a gRPC server.

public class Worker : BackgroundService
{
    private readonly Tester.TesterClient _client;
    private readonly IGreetRepository _greetRepository;

    public Worker(Tester.TesterClient client, IGreetRepository greetRepository)
    {
        _client = client;
        _greetRepository = greetRepository;
    }

    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var count = 0;
        while (!stoppingToken.IsCancellationRequested)
        {
            count++;

            var reply = await _client.SayHelloUnaryAsync(
                new HelloRequest { Name = $"Worker {count}" });

            _greetRepository.SaveGreeting(reply.Message);

            await Task.Delay(1000, stoppingToken);
        }
    }
}

The preceding type:

  • Follows the Explicit Dependencies Principle.
  • TesterClient is generated automatically by the tooling package Grpc.Tools based on the test.proto file, during the build process.
  • Expects dependency injection (DI) to provide instances of TesterClient and IGreetRepository. The app is configured to use the gRPC client factory to create TesterClient.
  • Can be tested with a mocked IGreetRepository service and TesterClient client using a mock object framework, such as Moq. A mocked object is a fabricated object with a predetermined set of property and method behaviors used for testing. For more information, see Integration tests in ASP.NET Core.

For more information on the C# assets automatically generated by Grpc.Tools, see gRPC services with C#: Generated C# assets.

Mock a gRPC client

gRPC clients are concrete client types that are generated from .proto files. The concrete gRPC client has methods that translate to the gRPC service in the .proto file. For example, a service called Greeter generates a GreeterClient type with methods to call the service.

A mocking framework can mock a gRPC client type. When a mocked client is passed to the type, the test uses the mocked method instead of sending a gRPC call to a server.

[Fact]
public async Task Greeting_Success_RepositoryCalled()
{
    // Arrange
    var mockRepository = new Mock<IGreetRepository>();

    var mockCall = CallHelpers.CreateAsyncUnaryCall(new HelloReply { Message = "Test" });
    var mockClient = new Mock<Tester.TesterClient>();
    mockClient
        .Setup(m => m.SayHelloUnaryAsync(
            It.IsAny<HelloRequest>(), null, null, CancellationToken.None))
        .Returns(mockCall);

    var worker = new Worker(mockClient.Object, mockRepository.Object);

    // Act
    await worker.StartAsync(CancellationToken.None);

    // Assert
    mockRepository.Verify(v => v.SaveGreeting("Test"));
}

The preceding unit test:

  • Mocks IGreetRepository and TesterClient using Moq.
  • Starts the worker.
  • Verifies SaveGreeting is called with the greeting message returned by the mocked TesterClient.

Additional resources