Cympatic.Extensions.Stub 1.0.1

Isolated testing of system components through contract testing

A C# .NET based, lightweight stub server that mimics the functionality of an external service, commonly used by microservices.

Key Features

• Test locally system and integration tests of system components
• Reduce the dependency on complex and/or expensive test environments
• Per-request conditional responses
• Recording requests
• Easy to use

By using contract testing[^1^] in integration tests for projects with dependencies on external services, the stub server can provide configurable responses for requests made to these services. Each request is recorded and can be validated as part of these integration tests. [^1^]: Consumer-driven Contract Testing (CDC)

The stub server creates a web host for the external service to handle the requests and responses for the external service made by the SUT. Creating the stub server can be done within a custom WebApplicationFactory [^2^] that might be available in the testproject for integration testing the SUT. An example of a custom WebApplicationFactory can be found in the example testproject.

[^2^]: Integration tests in ASP.NET Core

Usage

Setup StubServer in a custom WebApplicationFactory

Add the initialization of the stub server in the constructor of your custom WebApplicationFactory and create the API services for configuring responses and retrieving received requests.

_stubServer = new StubServer();
_setupResponseApiService = _stubServer.CreateApiService<SetupResponseApiService>();
_receivedRequestApiService = _stubServer.CreateApiService<ReceivedRequestApiService>();

Add proxy methodes for adding responses to the StubServer.

public Task<ResponseSetup> AddResponseSetupAsync(ResponseSetup responseSetup, CancellationToken cancellationToken = default)
    => _setupResponseApiService.AddAsync(responseSetup, cancellationToken);

public Task AddResponsesSetupAsync(IEnumerable<ResponseSetup> responseSetups, CancellationToken cancellationToken = default)
    => _setupResponseApiService.AddAsync(responseSetups, cancellationToken);

Add proxy methode for reading requests from the StubServer.

public Task<IEnumerable<ReceivedRequest>> FindReceivedRequestsAsync(ReceivedRequestSearchParams searchParams, CancellationToken cancellationToken = default)
    => _receivedRequestApiService.FindAsync(searchParams, cancellationToken);

Add proxy methodes for removing responses and received requests from the StubServer.

public Task ClearResponsesSetupAsync(CancellationToken cancellationToken = default)
    => _setupResponseApiService.RemoveAllAsync(cancellationToken);

public Task ClearReceivedRequestsAsync(CancellationToken cancellationToken = default)
    => _receivedRequestApiService.RemoveAllAsync(cancellationToken);

Override the Dispose since the StubServer is a disposable object.

protected override void Dispose(bool disposing)
{
    base.Dispose(disposing);

    if (disposing)
    {
        _stubServer.Dispose();
    }
}

Override the CreateHost of the WebApplicationFactory to configure the base address of the used external service.

protected override IHost CreateHost(IHostBuilder builder)
{
    builder.ConfigureServices((context, services) =>
    {
        context.Configuration["ExternalApi"] = _stubServer.BaseAddressStub.ToString();
    });

    return base.CreateHost(builder);
}

Use in unit test

Create a test class that implements a IClassFixture<> interface referencing the custom WebApplicationFactory to share object instances across the tests in the class.

public class WeatherForecastTests : IClassFixture<ExampleWebApplicationFactory<Program>>

In the constructor of the test class use the factory to create the HttpClient and clear the ResponseSetup and ReceivedRequest data from the StubServer

public WeatherForecastTests(ExampleWebApplicationFactory<Program> factory)
{
    _factory = factory;
    _httpClient = _factory.CreateClient();

    _factory.ClearResponsesSetupAsync();
    _factory.ClearReceivedRequestsAsync();
}

A typical test uses the factory to setup the response and process the request through the HttpClient. The request to the external service can be validated.

[Fact]
public async Task GetAllWeatherForecasts()
{
    static IEnumerable<WeatherForecast> GetItems()
    {
        for (var i = 0; i < NumberOfItems; i++)
        {
            yield return GenerateWeatherForecast(i);
        }
    }

    // Arrange
    var expected = GetItems().ToList();
    var responseSetup = new ResponseSetup
    {
        Path = "/external/api/weatherforecast",
        HttpMethods = [HttpMethod.Get.ToString()],
        ReturnStatusCode = HttpStatusCode.OK,
        Response = expected
    };
    await _factory.AddResponseSetupAsync(responseSetup);

    var expectedReceivedRequests = new List<ReceivedRequest>
    {
        new(responseSetup.Path, responseSetup.HttpMethods[0], responseSetup.Query, responseSetup.Headers, string.Empty, true)
    };

    // Act
    var response = await _httpClient.GetAsync("/weatherforecast");

    // Assert
    var actual = await response.Content.ReadFromJsonAsync<IEnumerable<WeatherForecast>>();
    actual.Should().BeEquivalentTo(expected);

    var actualReceivedRequests = await _factory.FindReceivedRequestsAsync(new ReceivedRequestSearchParams("/external/api/weatherforecast", [HttpMethod.Get.ToString()]));
    actualReceivedRequests.Should().BeEquivalentTo(expectedReceivedRequests, options => options
        .Excluding(_ => _.Headers)
        .Excluding(_ => _.Id)
        .Excluding(_ => _.CreatedDateTime));
}

• Prepare the ResponseSetup:
  • Set Path and HttpMethods to a partial path and HttpMethod of the expected request used by the external service.
  • Set ReturnStatusCode to the desired HttpStatusCode.
  • Set Response to the desired reponse of the external service.
• Add the ResponseSetup to the StubServer with the method AddResponseSetupAsync

• Process the request to the SUT using the HttpClient
• Verify the response from the SUT
• Verify the request made to the external service
  • Use the method FindReceivedRequestsAsync to locate the request made to the external service. The request can be found on a combination of Path, HttpMethod, and Query.